Spécification des clés API utilisateur

[Discourse]

Discourse contient un système pour générer des clés d’API par utilisateur si un protocole très spécifique est suivi. Cette fonctionnalité facilite l’accès « applicatif » aux instances Discourse sans nécessiter l’implication des modérateurs.

Description générale

En résumé :

1. Le client (application de bureau, plugin de navigateur, application mobile) génère une paire de clés privée/publique et une URL de retour
2. Le client redirige vers une route sur Discourse en lui fournissant sa clé publique
3. Discourse obtient l’approbation de l’utilisateur pour utiliser l’application
4. Discourse génère une clé d’API utilisateur
5. Discourse redirige vers l’URL de retour avec une charge utile chiffrée utilisant la clé publique contenant la clé d’API utilisateur

Détails

Cas d’utilisation :

1. Applications de bureau qui interrogent des sites Discourse au nom des utilisateurs finaux pour obtenir les comptes de notification sur plusieurs sites.
2. Applications mobiles qui interrogent des sites Discourse au nom des utilisateurs finaux et gèrent les notifications push.
3. Applications Web qui fournissent un tableau de bord aux utilisateurs finaux concernant divers sites Discourse.
4. Intégrations personnalisées avec des applications tierces qui consomment Discourse dans le cadre d’une application d’entreprise générale. Par exemple : intégrer les notifications de la communauté Discourse dans l’application hopscotch.

La conception :

Paramètres du site

• allow_user_api_key_scopes: étendues d’accès autorisées pour les clés d’API utilisateur. Les étendues sont définies ici. Les étendues intégrées disponibles sont : read, write, message_bus, push, one_time_password, notifications, session_info, bookmarks_calendar, user_status (les plugins peuvent enregistrer des étendues supplémentaires).

• user_api_key_allowed_groups: contrôle quels groupes sont autorisés à générer des clés d’API utilisateur (par défaut : administrateurs, modérateurs et trust_level_0)

• allowed_user_api_push_urls: liste des sites pouvant être des cibles pour les notifications push

• allowed_user_api_auth_redirects: destinations de redirection autorisées après la génération de la clé d’API utilisateur

Paramètres globaux

• max_user_api_reqs_per_minute: 20
• max_user_api_reqs_per_day: 2880

Éléments UX

Si des clés d’API utilisateur ont été accordées, Discourse affiche un onglet applications sur la page de l’utilisateur.
L’onglet applications listera :

• Le nom de l’application (par exemple : (« Discourse Notifier »))
• Date de dernière utilisation
• Date d’approbation
• Liste des étendues d’accès accordées
• Un bouton révoquer l’accès pour pouvoir révoquer facilement toutes les clés

Interface utilisateur d’autorisation de clé d’API

Chaque clé devra être explicitement autorisée par les utilisateurs finaux sur une page qui explique clairement ce qui se passe, par exemple :

« Discourse Notifier » demande l’accès suivant à votre compte :

• Lire et effacer les notifications
• Lire les informations de session de l’utilisateur
• Créer un jeton de connexion unique

[Autoriser]

Flux de génération de clé d’API

L’API ne nécessite qu’une seule requête GET du côté de l’utilisateur.

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

Depuis Discourse 2.1, ces clés d’API utilisateur expirent automatiquement si elles ne sont pas utilisées pendant de longues périodes. Le paramètre du site : revoke user api keys unused days est défini sur 180 par défaut.

Paramètres :

• auth_redirect: URL vers laquelle rediriger avec le jeton généré
• application_name: nom de l’application effectuant la requête (affiché dans l’onglet Applications du compte utilisateur)
• client_id: identifiant unique pour le client
• nonce: un nonce unique généré par le client. Il sera renvoyé dans la charge utile chiffrée afin que le client puisse vérifier l’authenticité de la réponse
• scopes: liste séparée par des virgules des étendues d’accès autorisées pour la clé, consultez allow user api key scopes pour la liste complète des étendues disponibles
• push_url: URL vers laquelle envoyer les notifications push (requis et valide uniquement si push ou notifications sont inclus dans les étendues)
• public_key: partie publique de la paire de clés générée par le client
• padding (optionnel) : le mode de rembourrage RSA à utiliser pour chiffrer la charge utile. Les valeurs acceptées sont pkcs1 (par défaut) ou oaep. OAEP est recommandé pour les nouvelles applications.

Après l’appel de /user-api-key/new avec les bons paramètres, 2 choses peuvent se produire :

1. Si l’utilisateur n’est pas connecté, nous le redirigerons vers la connexion (après la connexion, nous reprendrons l’autorisation)
2. Une fois qu’un utilisateur est connecté, l’interface utilisateur d’autorisation lui sera présentée.

Après l’autorisation, le système redirigera vers l’URL définie dans auth_redirect et inclura un paramètre payload chiffré contenant un objet JSON avec la clé d’API utilisateur générée (key), le nonce, l’état push (push) et la version de l’API (api). Si l’étendue one_time_password a été demandée, un paramètre de requête oneTimePassword chiffré séparé sera également inclus. client_id n’est pas renvoyé pour une sécurité accrue.

Vérification de la version de l’API

L’API d’utilisation des clés dans Discourse est versionnée. Les clients peuvent vérifier la version de l’API d’un site Discourse en effectuant une requête HEAD vers https://sitename.com/user-api-key/new. La réponse contiendra un en-tête nommé Auth-Api-Version contenant le numéro de version de l’API du site.

Consommation de l’API

La consommation de l’API client sera quelque peu différente de l’API d’administration actuelle.
Le client peut spécifier 2 en-têtes :

User-Api-Key (requis) : la clé qui a été générée

et

User-Api-Client-Id (optionnel) : fournissez ceci pour mettre à jour l’« identifiant client » stocké pour cette api_key dans la base de données.

Une fois ces en-têtes spécifiés, le client peut effectuer des requêtes contre l’API comme il le ferait normalement.

Génération d’un mot de passe de connexion unique

Depuis la version 4, l’API inclut une étendue spéciale : l’étendue one_time_password, qui permet aux clients d’utiliser la clé d’API utilisateur pour générer un mot de passe à usage unique. Si le client inclut cette étendue lors de la génération de la clé d’API en suivant les étapes ci-dessus, un oneTimePassword chiffré sera inclus en tant que paramètre de requête séparé dans la redirection vers le client.

Alternativement, le client peut effectuer une requête GET vers /user-api-key/otp avec les paramètres suivants :

• auth_redirect
• application_name
• public_key
• padding (optionnel)

et avec l’en-tête User-Api-Key.

Cette requête redirigera vers un écran dans Discourse qui demandera à l’utilisateur d’autoriser l’application à accéder au site. Si l’utilisateur approuve, le site redirigera vers l’URL définie dans auth_redirect et inclura un paramètre oneTimePassword chiffré avec un mot de passe à usage unique que le client pourra utiliser pour se connecter au site en demandant https://sitename.com/session/otp/ONE-TIME-PASSWORD. (Le mot de passe à usage unique n’est valable que 10 minutes.)

Révocation des clés d’API

Pour révoquer une clé d’API, effectuez une requête POST avec l’en-tête User-Api-Key et aucun paramètre vers /user-api-key/revoke.

---

Dernière révision par @SaraDev le 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]

Hi guys

Apologies if this is duplication but I am having trouble digesting the steps there even though they are very well put together

I have a discourse installation on https://forum.domain.com and a site on https://development.domain.com from which I need to make calls to the discourse installation to pull and set some data.

All requests work from postman with Api-Username and Api-Key - no problem

However for cross origin requests using JS discourse doesnt allow the Api-Username leading me down the path of the flow described in this thread i.e. using the User-Api-Key and the User-Api-Client-Id

I basically require a description of paramaters PUBLIC_KEY,NONCE,CLIENTID used in the sample request below and where I can get them…

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

Finally will this flow allow for seamless api requests from my https://development.domain.com to https://forum.domain.com without the need for authentication.

PS I have SSO set up between the forum and the site from which the requests are being made so the user will be logged in…

Thanks for any guidance

[sam (Sam Saffron)]

One sec, is this a per user thing? Are you allowing arbitrary users to do this?

Our server API supports header based auth these days so it can work with CORS just like the user api keys do. You would use the user api keys if you want to restrict scopes and allow end users to generate the keys vs admins.

[Alan_Murphy]

I wouldn’t see each user requiring a separate key no… One admin key should do what I need.

I can consume the api no problem through postman. For example a GET to /notifications.json?username=alanmurphy returns the data no problem using just api-key as a header.

If I trigger that request from the console of a discourse installation I get data back no problem also i.e.

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();

All Good:+1:

However, if I do this from the sub-domain I am wishing to contact discourse from, it tells me that it has been blocked by CORS policy: Request header field api-key is not allowed by Access-Control-Allow-Headers.

The allowed headers are:

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

If I could just get guidance on what auth params to pass for cross origin requests and where to get them that would be very helpful.

Ps. My discourse is set up to allow Cross Origin requests from the domain so I believe it is purely a headers issue

Thanks