Use chaves de API escopadas

Discourse · Setembro 22, 2020, 9:29pm

As Chaves de API permitem integrar o Discourse com outros sistemas ou automatizar diversas ações. No entanto, grande poder exige grande responsabilidade. Se um agente malicioso tiver acesso a uma Chave de API, poderá acessar dados sensíveis ou fazer alterações no seu site. Para mitigar isso e adicionar uma camada extra de segurança, agora você pode limitar o que uma Chave de API pode fazer usando escopos.

Escopos e parâmetros permitidos

Ao criar uma nova Chave de API, você pode selecionar quais escopos deseja. Se passar o mouse sobre o ícone , verá uma breve descrição do que ele faz. O botão mostrará as URLs associadas a esse escopo.

Opcionalmente, você também pode especificar quais parâmetros são aceitos. Use vírgulas para separar múltiplos valores.

Migrando chaves existentes

Quando adicionamos esse recurso, as chaves existentes se tornaram chaves “globais”. Para migrá-las para escopos, você precisará revogá-las e criar novas.

Adicionando escopos personalizados

Plugins podem adicionar escopos personalizados chamando o método add_api_key_scope:

github.com/discourse/discourse

lib/plugin/instance.rb

main


      
            reloadable_patch { Reviewable.add_custom_filter(filter) }
          end
          
          # Register a new API key scope.
          #
          # Example:
          # add_api_key_scope(:groups, { delete: { actions: %w[groups#add_members], params: %i[id] } })
          #
          # This scope lets you add members to a group. Additionally, you can specify which group ids are allowed.
          # The delete action is added to the groups resource.
          def add_api_key_scope(resource, action)
            DiscoursePluginRegistry.register_api_key_scope_mapping({ resource => action }, self)
          end
          
          # Register a new UserApiKey scope, and its allowed routes. Scope will be prefixed
          # with the (parameterized) plugin name followed by a colon.
          #
          # For example, if discourse-awesome-plugin registered this:
          #
          # add_user_api_key_scope(:read_my_route,
          #   methods: :get,

resource é um símbolo usado para agrupar escopos relacionados, enquanto action é um hash com os seguintes atributos:

actions: Uma lista contendo as ações de controlador permitidas. O formato é nome_do_controlador#nome_do_metodo.
methods: Uma lista de métodos HTTP permitidos (por exemplo, %i[get]). Use isso em vez de actions para corresponder pelo método HTTP em vez da ação do controlador.
params: Uma lista contendo os nomes dos parâmetros permitidos.
aliases: Um hash contendo um nome diferente para um parâmetro permitido.

Se quiser saber como os escopos básicos são definidos, veja:

github.com/discourse/discourse

app/models/api_key_scope.rb

main


      
          
          class << self
            def list_actions
              actions = %w[list#category_feed list#category_default list#latest_feed]
          
              %i[latest unread new top].each { |f| actions.concat(["list#category_#{f}", "list##{f}"]) }
          
              actions
            end
          
            def default_mappings
              return @default_mappings unless @default_mappings.nil?
          
              mappings = {
                global: {
                  read: {
                    methods: %i[get],
                  },
                },
                topics: {
                  write: {

nickhingston · Setembro 23, 2020, 7:43am

Parece que estou recebendo uma resposta 403 ao buscar categorias com uma chave de API de somente leitura.

curl -X GET "https://mysite/categories.json" \
-H "Api-Key: mykey" \
-H "Api-Username: system"

Onde eu li que tenho permissões de leitura e read_list para tópicos na chave de API. Por exemplo, /top.json funciona com a mesma chave. O endpoint funciona quando uso uma ‘Chave Global’.

Gostaria de colocar a chave de API no meu cliente para ler a lista de categorias e tópicos, então é importante ter uma chave de somente leitura!

Alguma orientação?

nickhingston · Setembro 23, 2020, 10:03am

Curiosamente, funciona se nenhuma credencial for usada!

k
ou seja, curl -X GET "https://mysite/categories.json"

Roman · Setembro 23, 2020, 2:32pm

Infelizmente, devido ao grande número de endpoints disponíveis, incluímos apenas alguns escopos padrão. Podemos adicionar novos no futuro, mas, enquanto isso, você precisará estendê-los para atender às suas necessidades.

Se você usar uma Chave de API com escopo, chamar endpoints não incluídos nos escopos escolhidos não funcionará. Você pode clicar no botão para ver quais URLs são aceitos.

Isso só funciona para sites públicos. Além disso, você não verá coisas como categorias privadas, a menos que esteja logado e tenha permissões suficientes.

Dannii · Setembro 26, 2020, 7:53am

Vocês estão aceitando sugestões para escopos adicionais?

Uma coisa que eu gostaria de fazer usando a API do nosso site seria permitir que outro site verifique se um usuário existe com um endereço de e-mail e o adicione a um grupo, caso positivo. Confio no site (outro site dentro da nossa organização matriz), mas restringir as opções de acesso apenas ao necessário parece sensato, se for uma opção disponível.

fzngagan · Setembro 26, 2020, 8:35am

Estou super feliz que tenham aberto uma API para plugins. Você pode começar com um plugin e ver se ele pode ser incorporado ao núcleo.

riking · Setembro 26, 2020, 10:17am

Acredito que pr-welcome para qualquer escopo geralmente útil que você possa imaginar. Por exemplo, group_membership.edit?

Tópico		Respostas	Visualizações
What scopes exactly does the Wordpress API key need? WordPress	13	1701	24 de Maio de 2022
Create and configure an API key Integrations how-to , rest-api	6	30752	10 de Maio de 2024
Get an API key's scopes and user level via the API Development rest-api	0	609	16 de Novembro de 2023
Get API Key only for adding/removing users from a group Development rest-api	1	468	23 de Setembro de 2022
Granular API support for creating users? Support rest-api	2	56	17 de Outubro de 2025

Use chaves de API escopadas

Escopos e parâmetros permitidos

Migrando chaves existentes

Adicionando escopos personalizados

Tópicos relacionados