Spécification des clés API utilisateur

[Discourse]

Discourse contient un système de génération de clés API par utilisateur si un protocole très spécifique est suivi. Cette fonctionnalité facilite l’accès “application” aux instances Discourse sans avoir besoin d’impliquer les modérateurs.

Description générale

De manière générale :

1. Le client (application de bureau, extension 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 donnant sa clé publique

3. Discourse obtient l’approbation de l’utilisateur pour utiliser l’application

4. Discourse génère une clé API utilisateur

5. Discourse redirige vers l’URL de retour avec une charge utile chiffrée utilisant la clé API publique contenant la clé API utilisateur

Détails

Cas d’utilisation :

1. Applications de bureau qui interrogent les sites Discourse au nom des utilisateurs finaux pour obtenir les nombres de notifications sur plusieurs sites.

2. Applications mobiles qui interrogent les sites Discourse au nom des utilisateurs finaux et gèrent les notifications push

3. Applications web qui fournissent un tableau de bord pour les utilisateurs finaux sur 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 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 API utilisateur (par défaut : administrateurs, modérateurs et trust_level_0)

• allowed_user_api_push_urls : liste des sites qui peuvent ê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é API utilisateur

Paramètres globaux

• max_user_api_reqs_per_minute : 50
• max_user_api_reqs_per_day : 4000

Éléments UX

Si des clés API utilisateur ont été accordées, Discourse affiche un onglet apps dans la page utilisateur.

L’onglet apps listera :

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

Interface d’autorisation des clés 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 les accès suivants à votre compte :

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

[Autoriser]

Flux de génération de clés API

L’API ne nécessite qu’une seule requête GET de la part de l’utilisateur.

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

À partir de Discourse 2.1, ces clés 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 : le nom de l’application effectuant la requête (sera affiché dans l’onglet Apps du compte utilisateur)
• client_id : un identifiant unique pour le client
• nonce : un nonce unique généré par le client. Cela sera renvoyé dans la charge utile chiffrée pour 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é, voir 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 : la partie publique de la paire de clés générée par le client
• padding (facultatif) : le mode de remplissage 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 paramètres corrects, deux choses peuvent se produire

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

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é API utilisateur générée (key), le nonce, l’état push (push) et la version 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é supplémentaire.

Vérification de la version API

L’API des clés utilisateur dans Discourse est versionnée. Les clients peuvent vérifier la version 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 admin 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 (facultatif) : fournissez ceci pour mettre à jour l’« client id » stocké pour cette clé API 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

À partir de la version 4, l’API inclut une étendue spéciale : l’étendue one_time_password, qui permet aux clients d’utiliser la clé API utilisateur pour générer un mot de passe unique. Si le client inclut cette étendue lors de la génération de la clé 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 (facultatif)

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’accès de l’application 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 unique que le client peut utiliser pour se connecter au site en demandant https://sitename.com/session/otp/MOT-DE-PASSE-UNIQUE. (Le mot de passe unique n’est valide que pendant 10 minutes.)

Révocation des clés API

Pour révoquer une clé 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]

Salut à tous,

Désolé si c’est une redite, mais j’ai du mal à assimiler les étapes, même si elles sont très bien expliquées.

J’ai une installation Discourse sur https://forum.domain.com et un site sur https://development.domain.com depuis lequel je dois effectuer des appels vers l’installation Discourse pour récupérer et définir certaines données.

Toutes les requêtes fonctionnent depuis Postman avec Api-Username et Api-Key — aucun problème.

Cependant, pour les requêtes cross-origin en JS, Discourse ne permet pas l’utilisation de Api-Username, ce qui m’oriente vers le flux décrit dans ce fil de discussion, à savoir l’utilisation de User-Api-Key et User-Api-Client-Id.

J’aurais besoin d’une description des paramètres PUBLIC_KEY, NONCE et CLIENTID utilisés dans l’exemple de requête ci-dessous, ainsi que de savoir où les obtenir…

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

Enfin, ce flux permettra-t-il des requêtes API transparentes depuis mon https://development.domain.com vers https://forum.domain.com sans nécessiter d’authentification ?

PS : J’ai configuré SSO entre le forum et le site depuis lequel les requêtes sont effectuées, donc l’utilisateur sera connecté.

Merci pour tout conseil.

[sam (Sam Saffron)]

Un instant, s’agit-il d’une fonctionnalité par utilisateur ? Autorisez-vous n’importe quel utilisateur à faire cela ?

Notre API serveur prend désormais en charge l’authentification basée sur les en-têtes, ce qui permet de fonctionner avec CORS, tout comme les clés API utilisateur. Vous utiliserez les clés API utilisateur si vous souhaitez restreindre les portées et permettre aux utilisateurs finaux de générer les clés plutôt qu’aux administrateurs.

[Alan_Murphy]

Je ne pense pas que chaque utilisateur ait besoin d’une clé distincte… Une seule clé d’administration devrait suffire à mes besoins.

Je peux consommer l’API sans problème via Postman. Par exemple, une requête GET vers /notifications.json?username=alanmurphy renvoie les données sans problème en utilisant simplement api-key comme en-tête.

Si je déclenche cette requête depuis la console d’une installation Discourse, je reçois également les données sans problème, c’est-à-dire :

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

Tout est bon

Cependant, si je fais cela depuis le sous-domaine à partir duquel je souhaite contacter Discourse, il indique que la requête a été bloquée par la politique CORS : Le champ d’en-tête de requête api-key n’est pas autorisé par Access-Control-Allow-Headers.

Les en-têtes autorisés sont :

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

Si vous pouviez simplement me guider sur quels paramètres d’authentification passer pour les requêtes interdomaines et où les obtenir, cela serait très utile.

P.S. Mon Discourse est configuré pour autoriser les requêtes interdomaines depuis le domaine, donc je pense qu’il s’agit purement d’un problème d’en-têtes.

Merci