Especificação das chaves de API do usuário

[Discourse]

O Discourse possui um sistema para gerar chaves de API por usuário caso um protocolo muito específico seja seguido. Esse recurso facilita o acesso de “aplicações” às instâncias do Discourse sem a necessidade de envolver moderadores.

Descrição geral

De forma geral:

1. O cliente (aplicativo de desktop, plug-in de navegador, aplicativo móvel) gera um par de chaves privada/pública e uma URL de retorno.

2. O cliente redireciona para uma rota no Discourse, fornecendo sua chave pública ao Discourse.

3. O Discourse obtém a aprovação do usuário para usar o aplicativo.

4. O Discourse gera uma chave de API do usuário.

5. O Discourse redireciona de volta para a URL de retorno com uma carga útil criptografada usando a chave pública da API, contendo a chave de API do usuário.

Detalhes

Casos de uso:

1. Aplicativos de desktop que consultam sites do Discourse em nome dos usuários finais para obter contagens de notificações em vários sites.

2. Aplicativos móveis que consultam sites do Discourse em nome dos usuários finais e gerenciam notificações push.

3. Aplicativos da web que fornecem um painel para usuários finais sobre vários sites do Discourse.

4. Integrações personalizadas com aplicativos de terceiros que consomem o Discourse como parte de um aplicativo corporativo geral. Ex.: integrar notificações da comunidade do Discourse ao aplicativo Hopscotch.

O design:

Configurações do site

• allow_user_api_key_scopes: escopos de acesso permitidos para chaves de API de usuário. Os escopos são definidos aqui. Os escopos integrados disponíveis são: read, write, message_bus, push, one_time_password, notifications, session_info, bookmarks_calendar, user_status (plug-ins podem registrar escopos adicionais).

• user_api_key_allowed_groups: controla quais grupos têm permissão para gerar chaves de API de usuário (padrão: administradores, moderadores e trust_level_0)

• allowed_user_api_push_urls: lista de sites que podem ser destinos para notificações push

• allowed_user_api_auth_redirects: destinos de redirecionamento permitidos após a geração da chave de API de usuário

Configurações globais

• max_user_api_reqs_per_minute: 50
• max_user_api_reqs_per_day: 4000

Elementos de UX

Se alguma chave de API de usuário tiver sido concedida, o Discourse exibe uma aba aplicativos na página do usuário.

A aba aplicativos listará:

• O nome do aplicativo, por exemplo: (“Discourse Notifier”)
• Data do último uso
• Data de aprovação
• Lista de escopos de acesso concedidos
• Um botão revogar acesso para que você possa revogar facilmente quaisquer chaves

Interface de autorização de chave de API

Cada chave precisará ser explicitamente autorizada pelos usuários finais em uma página que explique claramente o que está acontecendo, por exemplo:

“Discourse Notifier” está solicitando o seguinte acesso à sua conta:

• Ler e limpar notificações
• Ler informações de sessão do usuário
• Criar um token de login único

[Autorizar]

Fluxo de geração de chave de API

A API requer apenas uma única solicitação GET do lado do usuário.

https://nomedosite.com/user-api-key/new

A partir do Discourse 2.1, essas chaves de API de usuário agora expiram automaticamente se ficarem sem uso por longos períodos. A configuração do site: revoke user api keys unused days está definida como 180 por padrão.

Parâmetros:

• auth_redirect: URL para redirecionar de volta com o token gerado
• application_name: o nome do aplicativo que está fazendo a solicitação (será exibido na aba Aplicativos da conta do usuário)
• client_id: um identificador exclusivo para o cliente
• nonce: um nonce exclusivo gerado pelo cliente. Isso será ecoado de volta na carga útil criptografada para que o cliente possa verificar a autenticidade da resposta
• scopes: lista separada por vírgulas de escopos de acesso permitidos para a chave, consulte allow user api key scopes para a lista completa de escopos disponíveis
• push_url: URL para enviar notificações push (obrigatório e válido apenas se push ou notifications estiverem incluídos nos escopos)
• public_key: a parte pública do par de chaves gerado pelo cliente
• padding (opcional): o modo de preenchimento RSA a ser usado para criptografar a carga útil. Os valores aceitos são pkcs1 (padrão) ou oaep. O OAEP é recomendado para novos aplicativos

Depois que /user-api-key/new for chamado com os parâmetros corretos, duas coisas podem acontecer

1. Se o usuário não estiver conectado, redirecionaremos para o login (após o login, retomaremos a autorização)
2. Uma vez que o usuário esteja conectado, ele será apresentado à interface de autorização

Após a autorização ser permitida, o sistema redirecionará de volta para a URL definida em auth_redirect e incluirá um parâmetro payload criptografado contendo um objeto JSON com a chave de API de usuário gerada (key), o nonce, o status de push (push) e a versão da API (api). Se o escopo one_time_password foi solicitado, um parâmetro de consulta oneTimePassword criptografado separado também será incluído. O client_id não é ecoado de volta para segurança extra.

Verificando a versão da API

A API de chave de uso no Discourse é versionada. Os clientes podem verificar a versão da API de um site do Discourse fazendo uma solicitação HEAD para https://nomedosite.com/user-api-key/new. A resposta conterá um cabeçalho chamado Auth-Api-Version contendo o número da versão da API do site.

Consumindo a API

Consumir a API do cliente será um pouco diferente da API de administrador atual.

O cliente pode especificar 2 cabeçalhos:

User-Api-Key (obrigatório): a chave que foi gerada

e

User-Api-Client-Id (opcional): forneça isso para atualizar o ‘client id’ armazenado para esta chave de API no banco de dados.

Uma vez que esses cabeçalhos são especificados, o cliente pode realizar solicitações contra a API como faria normalmente.

Gerando uma senha de login único

A partir da versão 4, a API inclui um escopo especial: o escopo one_time_password, que permite que os clientes usem a chave de API do usuário para gerar uma senha de uso único. Se o cliente incluir este escopo ao gerar a chave de API seguindo as etapas acima, um oneTimePassword criptografado será incluído como um parâmetro de consulta separado no redirecionamento de volta para o cliente.

Alternativamente, o cliente pode fazer uma solicitação GET para /user-api-key/otp com os seguintes parâmetros:

• auth_redirect
• application_name
• public_key
• padding (opcional)

e com o cabeçalho User-Api-Key.

Esta solicitação redirecionará para uma tela no Discourse que pedirá ao usuário para permitir que o aplicativo acesse o site. Se o usuário aprovar, o site redirecionará de volta para a URL definida em auth_redirect e incluirá um parâmetro oneTimePassword criptografado com uma senha de uso único que o cliente pode usar para fazer login no site solicitando https://nomedosite.com/session/otp/SENHA-UNICA. (A senha de uso único é válida apenas por 10 minutos.)

Revogando chaves de API

Para revogar uma chave de API, faça uma solicitação POST com o cabeçalho User-Api-Key e sem parâmetros para /user-api-key/revoke.

---

Última revisão por @SaraDev em 2022-07-13T00:00:00Z

[elijah (Eli the Bearded)]

There are places I’ve strongly considered writing a delayed post tool, so I can compose a bunch of “word of the day” type things to keep going while I’m on vacation. Doing it without proper API access and pretending to be a browser seems somewhat more complicated than on other forum software.

(Just as an example of another use case.)

[sam (Sam Saffron)]

That is a good example, but keep in mind, our default will be only to enable read tokens, not write ones. Site admins will have to opt to allow write tokens.

Completely agree that the _t cookie hacks are a huge problem.

[jesselperry (Jesse Perry)]

Does max_user_api_calls_per_key_day setting apply to admin-created keys at /admin/api?

[sam (Sam Saffron)]

Nope only to user api keys, we can look at adding extra limits for standard Api keys, it is a good safeguard

[sckott]

To be clear, this is not implemented yet, correct?

[RGJ (Richard - Communiteq)]

No, it’s there (for almost 2,5 years now) - Admin - Settings - User API.

[codinghorror (Jeff Atwood)]

As of Discourse 2.1 these user api keys now auto-expire if left unused for long periods of time, correct @sam?

[sam (Sam Saffron)]

Correct the site setting: expire user api keys days is set to 180 out of the box.

[sckott]

@RGJ

No, it’s there (for almost 2,5 years now) - Admin - Settings - User API.

Okay, but you have to have admin access to see that page yes? And as an admin, it seems I can only create 1 key, so can’t create many keys for different users. confused.

[blake (Blake Erickson)]

What are you trying to accomplish? It’s not clear because there is this (user api keys) and regular API tokens (which is what I think you are after) that admins can create for multiple users, but you have to do that from the individual user’s page inside of the admin dashboard by clicking on the “generate” button on the “API Key” field.

[sckott]

Thanks! Yes, “regular API tokens” for users is what i was after. I’m sure I’d seen that a million times, and never realized it was there.

[vsoch (Vanessasaurus)]

Hey everyone I’m not sure if this was resolved? I see that it’s possible to create an “All Users” and (per user) level API token as an admin, but I’m interested in giving a user the power to generate his/her own token. Has there been work done on this? It sounds like the original thread was getting at this idea, and then it was lost. Thanks!

[sam (Sam Saffron)]

Download the mobile App and then add a site, that uses the user api key system you have to follow a very strict workflow, no plans to expose arbitrary generation of keys in user prefs

[vsoch (Vanessasaurus)]

Thank you! I downloaded the app, and then realized that the sites I belong to don’t have this enabled (I’ve been testing on my local machine with the Dockerized discourse). Just to make sure we are talking about the same thing - I’m interested in generating tokens to use just a scoped subset of functions (and not global API keys to do all the things). Is this what you are talking about?

It seems like, given that there is an endpoint to generate tokens, it would be logical to provide this function (to users with a certain trust level, for example) from within the site. Otherwise, it would need to be the case that the site generates some external page (with a server to hide an admin token) to generate the keys for the user. Is it the case that 1. there is no internal generation of tokens for the user (and why not?) and 2. Nobody has created some external app (javascript, flask, anything really) to perform this action?

[sam (Sam Saffron)]

@vsoch

Is this what you are talking about?

Yes.

@vsoch

it would be logical to provide this function (to users with a certain trust level, for example) from within the site. Otherwise, it would need to be the case that the site generates some external page (with a server to hide an admin token) to generate the keys for the user. Is it the case that 1. there is no internal generation of tokens for the user (and why not?) and 2. Nobody has created some external app (javascript, flask, anything really) to perform this action?

Possibly, conceptually

1. This is tricky to consume cause you need to use custom HTTP headers (by design)

2. It would be very hard to educate even TL3 users about what the point is of this thing.

I prefer not to ship UI for this in core, but maybe you should write a plugin for your specific use case?

Can you explain a bit more about the “why” here?

The design of the system centers around “I have an external dedicated program”, “this program knows how to follow Discourse protocol”, “It asks for token”

API keys (non user ones) are much easier to consume cause you just append them after the ?

[ymi]

@sam

Consuming the API

Consuming the client API will be somewhat different that the current admin API.

Client can specify 2 headers:

User-Api-Key (required): the key that was generated

and

User-Api-Client-Id (optional): supply this to update the ‘client id’ stored for this api_key in the database.

Once those headers are specified client can perform requests against the API just as they would normally.

Can I pass the API key generated from the user page on this? I was trying to use that API key and seeing ‘You are not permitted to view the requested resource.’ error on /categories.json API request

[Alan_Murphy]

Olá pessoal

Peço desculpas se isso já foi discutido, mas estou com dificuldade em entender os passos, mesmo que estejam muito bem explicados.

Tenho uma instalação do Discourse em https://forum.domain.com e um site em https://development.domain.com, do qual preciso fazer chamadas à instalação do Discourse para buscar e definir alguns dados.

Todos os pedidos funcionam no Postman com Api-Username e Api-Key — sem problemas.

No entanto, para solicitações cross-origin usando JS, o Discourse não permite o uso do Api-Username, o que me levou ao fluxo descrito neste tópico, ou seja, usar o User-Api-Key e o User-Api-Client-Id.

Preciso basicamente de uma descrição dos parâmetros PUBLIC_KEY, NONCE e CLIENTID usados na solicitação de exemplo abaixo e de onde posso obtê-los…

https://forum.domain.com/user-api-key/new?public_key=PUBLIC_KEY&nonce=NONCE&scopes=SCOPES&client_id=CLIENTID&application_name=DEVELOP&auth_redirect=XXX

Por fim, esse fluxo permitirá solicitações de API sem interrupções do meu https://development.domain.com para https://forum.domain.com sem a necessidade de autenticação?

PS: Já configurei o SSO entre o fórum e o site de onde as solicitações estão sendo feitas, então o usuário já estará logado.

Obrigado por qualquer orientação.

[sam (Sam Saffron)]

Um segundo, isso é algo por usuário? Vocês estão permitindo que usuários arbitrários façam isso?

A API do nosso servidor suporta autenticação baseada em cabeçalhos atualmente, então pode funcionar com CORS assim como as chaves de API do usuário. Você usaria as chaves de API do usuário se quiser restringir escopos e permitir que usuários finais gerem as chaves, em vez de administradores.

[Alan_Murphy]

Não acredito que cada usuário precise de uma chave separada… Uma única chave de administrador deve atender ao que preciso.

Posso consumir a API sem problemas pelo Postman. Por exemplo, um GET para /notifications.json?username=alanmurphy retorna os dados corretamente usando apenas api-key como cabeçalho.

Se eu disparar essa solicitação do console de uma instalação do Discourse, também recebo os dados sem problemas, ou seja:

var xhr = new XMLHttpRequest();
xhr.addEventListener(“readystatechange”, function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open(“GET”, “https://**********.com/notifications.json?username=alanmurphy”);
xhr.setRequestHeader(“api-key”, “d06ca53322d1fbaf383a6394d6c229e56871342d2cad953a0fe26c19df7645ba”);
xhr.setRequestHeader(“api-userame”, “system”);
xhr.send();

Tudo certo:+1:

No entanto, se eu fizer isso a partir do subdomínio de onde pretendo contatar o Discourse, ele informa que foi bloqueado pela política CORS: O campo de cabeçalho da solicitação api-key não é permitido por Access-Control-Allow-Headers.

Os cabeçalhos permitidos são:

Content-Type, Cache-Control, X-Requested-With, X-CSRF-Token, Discourse-Visible, User-Api-Key, User-Api-Client-Id

Se pudesse receber orientação sobre quais parâmetros de autenticação passar para solicitações entre origens diferentes e onde obtê-los, seria muito útil.

P.S.: Meu Discourse está configurado para permitir solicitações entre origens diferentes a partir do domínio, então acredito que seja puramente uma questão de cabeçalhos.

Obrigado.