Especificación de claves de API de usuario

[Discourse]

Discourse incluye un sistema para generar claves de API por usuario si se sigue un protocolo muy específico. Esta función facilita el acceso de “aplicaciones” a las instancias de Discourse sin necesidad de involucrar a los moderadores.

Descripción general

En términos generales:

1. El cliente (aplicación de escritorio, complemento del navegador, aplicación móvil) genera un par de claves privada/pública y una URL de retorno.

2. El cliente redirige a una ruta en Discourse proporcionándole su clave pública.

3. Discourse obtiene la aprobación del usuario para utilizar la aplicación.

4. Discourse genera una clave de API de usuario.

5. Discourse redirige de nuevo a la URL de retorno con una carga útil cifrada utilizando la clave pública de la API, que contiene la clave de API del usuario.

Detalles

Casos de uso:

1. Aplicaciones de escritorio que consultan sitios de Discourse en nombre de los usuarios finales para obtener recuentos de notificaciones en varios sitios.

2. Aplicaciones móviles que consultan sitios de Discourse en nombre de los usuarios finales y gestionan notificaciones push.

3. Aplicaciones web que proporcionan un panel de control para los usuarios finales sobre varios sitios de Discourse.

4. Integraciones personalizadas con aplicaciones de terceros que consumen Discourse como parte de una aplicación general de la empresa. Por ejemplo: integrar las notificaciones de la comunidad de Discourse en la aplicación Hopscotch.

El diseño:

Configuración del sitio

• allow_user_api_key_scopes: ámbitos de acceso permitidos para las claves de API de usuario. Los ámbitos se definen aquí. Los ámbitos integrados disponibles son: read, write, message_bus, push, one_time_password, notifications, session_info, bookmarks_calendar, user_status (los complementos pueden registrar ámbitos adicionales).

• user_api_key_allowed_groups: controla qué grupos pueden generar claves de API de usuario (por defecto: administradores, moderadores y trust_level_0).

• allowed_user_api_push_urls: lista de sitios que pueden ser destinos para notificaciones push.

• allowed_user_api_auth_redirects: destinos de redirección permitidos después de la generación de la clave de API de usuario.

Configuración global

• max_user_api_reqs_per_minute: 50
• max_user_api_reqs_per_day: 4000

Elementos de la interfaz de usuario

Si se han concedido claves de API de usuario, Discourse muestra una pestaña apps en la página del usuario.

La pestaña apps listará:

• El nombre de la aplicación, por ejemplo: (“Discourse Notifier”)
• Fecha de último uso
• Fecha de aprobación
• Lista de ámbitos de acceso concedidos
• Un botón revoke access para que puedas revocar fácilmente cualquier clave

Interfaz de autorización de claves de API

Cada clave deberá ser autorizada explícitamente por los usuarios finales en una página que explique claramente qué está ocurriendo, por ejemplo:

“Discourse Notifier” está solicitando los siguientes accesos a tu cuenta:

• Leer y borrar notificaciones
• Leer información de sesión del usuario
• Crear un token de inicio de sesión único

[Autorizar]

Flujo de generación de claves de API

La API solo requiere una única solicitud GET por parte del usuario.

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

A partir de Discourse 2.1, estas claves de API de usuario caducan automáticamente si no se utilizan durante largos períodos de tiempo. La configuración del sitio: revoke user api keys unused days está establecida en 180 por defecto.

Parámetros:

• auth_redirect: URL a la que redirigir con el token generado.
• application_name: el nombre de la aplicación que realiza la solicitud (se mostrará en la pestaña Apps de la cuenta del usuario).
• client_id: un identificador único para el cliente.
• nonce: un nonce único generado por el cliente. Esto se devolverá en la carga útil cifrada para que el cliente pueda verificar la autenticidad de la respuesta.
• scopes: lista separada por comas de ámbitos de acceso permitidos para la clave, consulta allow user api key scopes para ver la lista completa de ámbitos disponibles.
• push_url: URL para enviar notificaciones push (requerido y válido solo si push o notifications están incluidos en los ámbitos).
• public_key: la parte pública del par de claves generado por el cliente.
• padding (opcional): el modo de relleno RSA a utilizar para cifrar la carga útil. Los valores aceptados son pkcs1 (por defecto) o oaep. Se recomienda OAEP para nuevas aplicaciones.

Después de llamar a /user-api-key/new con los parámetros correctos, pueden ocurrir dos cosas:

1. Si el usuario no ha iniciado sesión, se redirigirá al inicio de sesión (después de iniciar sesión, se reanudará la autorización).
2. Una vez que el usuario ha iniciado sesión, se le mostrará la interfaz de autorización.

Después de que se permita la autorización, el sistema redirigirá de nuevo a la URL definida en auth_redirect e incluirá un parámetro payload cifrado que contiene un objeto JSON con la clave de API de usuario generada (key), el nonce, el estado de push (push) y la versión de la API (api). Si se solicitó el ámbito one_time_password, también se incluirá un parámetro de consulta oneTimePassword cifrado por separado. client_id no se devuelve por seguridad adicional.

Verificación de la versión de la API

La API de claves de usuario en Discourse está versionada. Los clientes pueden verificar la versión de la API de un sitio de Discourse realizando una solicitud HEAD a https://sitename.com/user-api-key/new. La respuesta contendrá un encabezado llamado Auth-Api-Version que contiene el número de versión de la API del sitio.

Consumo de la API

El consumo de la API de cliente será algo diferente a la actual API de administrador.

El cliente puede especificar 2 encabezados:

User-Api-Key (obligatorio): la clave que fue generada

y

User-Api-Client-Id (opcional): proporciona esto para actualizar el ‘client id’ almacenado para esta clave de API en la base de datos.

Una vez especificados esos encabezados, el cliente puede realizar solicitudes contra la API tal como lo haría normalmente.

Generación de una contraseña de inicio de sesión único

A partir de la versión 4, la API incluye un ámbito especial: el ámbito one_time_password, que permite a los clientes utilizar la clave de API de usuario para generar una contraseña de un solo uso. Si el cliente incluye este ámbito al generar la clave de API siguiendo los pasos anteriores, se incluirá un oneTimePassword cifrado como un parámetro de consulta separado en la redirección de vuelta al cliente.

Alternativamente, el cliente puede realizar una solicitud GET a /user-api-key/otp con los siguientes parámetros:

• auth_redirect
• application_name
• public_key
• padding (opcional)

y con el encabezado User-Api-Key.

Esta solicitud redirigirá a una pantalla en Discourse que le pedirá al usuario que permita que la aplicación acceda al sitio. Si el usuario aprueba, el sitio redirigirá de nuevo a la URL definida en auth_redirect e incluirá un parámetro oneTimePassword cifrado con una contraseña de un solo uso que el cliente puede utilizar para iniciar sesión en el sitio solicitando https://sitename.com/session/otp/ONE-TIME-PASSWORD. (La contraseña de un solo uso es válida solo durante 10 minutos.)

Revocación de claves de API

Para revocar una clave de API, realiza una solicitud POST con el encabezado User-Api-Key y sin parámetros a /user-api-key/revoke.

---

Última revisión por @SaraDev el 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]

Hola a todos

Disculpen si esto es una duplicación, pero tengo dificultades para comprender los pasos, aunque están muy bien explicados.

Tengo una instalación de Discourse en https://forum.domain.com y un sitio en https://development.domain.com, desde el cual necesito hacer llamadas a la instalación de Discourse para obtener y establecer algunos datos.

Todas las solicitudes funcionan desde Postman con Api-Username y Api-Key, sin problemas.

Sin embargo, para las solicitudes entre orígenes usando JS, Discourse no permite el uso de Api-Username, lo que me lleva a seguir el flujo descrito en este hilo, es decir, usar User-Api-Key y User-Api-Client-Id.

Básicamente, necesito una descripción de los parámetros PUBLIC_KEY, NONCE y CLIENTID utilizados en la solicitud de ejemplo a continuación, y dónde puedo obtenerlos…

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

Finalmente, ¿este flujo permitirá solicitudes de API fluidas desde mi https://development.domain.com hacia https://forum.domain.com sin necesidad de autenticación adicional?

PD: Ya tengo SSO configurado entre el foro y el sitio desde el cual se realizan las solicitudes, por lo que el usuario ya estará conectado.

Gracias por cualquier orientación.

[sam (Sam Saffron)]

Un momento, ¿esto es algo por usuario? ¿Están permitiendo que usuarios arbitrarios hagan esto?

Nuestra API de servidor ahora admite autenticación basada en encabezados, por lo que puede funcionar con CORS igual que las claves de API de usuario. Usarías las claves de API de usuario si deseas restringir los ámbitos y permitir que los usuarios finales generen las claves en lugar de los administradores.

[Alan_Murphy]

No creo que sea necesario que cada usuario tenga una clave distinta… Una sola clave de administrador debería bastar para lo que necesito.

Puedo consumir la API sin problemas a través de Postman. Por ejemplo, una solicitud GET a /notifications.json?username=alanmurphy devuelve los datos sin inconvenientes, usando únicamente api-key como encabezado.

Si ejecuto esa solicitud desde la consola de una instalación de Discourse, también obtengo los datos sin problemas, es decir:

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

Todo correcto:+1:

Sin embargo, si lo hago desde el subdominio desde el cual deseo contactar a Discourse, me indica que ha sido bloqueado por la política CORS: El campo de encabezado de solicitud api-key no está permitido por Access-Control-Allow-Headers.

Los encabezados permitidos son:

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

Si pudiera recibir orientación sobre qué parámetros de autenticación enviar para solicitudes entre orígenes y dónde obtenerlos, sería de gran ayuda.

PD: Mi instalación de Discourse está configurada para permitir solicitudes entre orígenes desde el dominio, así que creo que el problema es únicamente de encabezados.

Gracias.