OAuth 2.0 Authorization Server
El servidor de autorización OAuth 2.0 permite que aplicaciones de terceros y apps nativas obtengan tokens de acceso limitados en nombre de usuarios, sin exponer credenciales de larga duración.
RFCs implementados: 8414 (metadata), 7591 (registro dinámico), 8252 (loopback), 7636 (PKCE), 8707 (resource indicators/audience).
Los clientes de navegador pueden registrarse con token_endpoint_auth_method: "none": la respuesta no contiene client_secret porque el navegador no puede guardar secretos. Si se omite este campo, se conserva el registro confidencial existente.
Endpoints
| Método | Ruta | Descripción |
|---|---|---|
GET | /.well-known/oauth-authorization-server | Metadata del servidor — issuer, endpoints, code_challenge_methods_supported |
POST | /oauth/register | Registro dinámico de cliente — rate-limited 5/IP/60s |
POST | /oauth/authorize | Solicitud de autorización con PKCE S256 obligatorio — rate-limited 20/IP/60s |
POST | /oauth/token | Canje de código por token y renovación con refresh — rate-limited 20/IP/60s |
GET | /oauth/authorizations | Lista autorizaciones conectadas de la empresa autenticada |
POST | /oauth/authorizations/:id/revoke | Revoca una autorización conectada — invalida tokens vigentes |
Los endpoints de metadata, registro, autorización y token son públicos (sin JWT). Los endpoints de autorizaciones conectadas requieren Bearer JWT (sesión de usuario).
Scope interno reservado
El servidor publica nimo:application-projects:promote en la metadata OAuth para el BFF confidencial de Nimo. Este scope está reservado al client_id exacto indicado en NIMO_INTERNAL_OAUTH_CLIENT_ID, cuyo registro en oauth_clients debe ser confidencial y tener el hash de NIMO_INTERNAL_OAUTH_CLIENT_SECRET. El secreto solo existe en configuración de servidor; el browser nunca recibe el nbt_ access token ni el client secret.
La promoción sigue siendo shareable=false y publicSafe=false. El backend valida en cada request el cliente, scope, expiración (máximo 15 minutos), empresa del token y membresía OWNER o ADMIN vigente. DCR no puede seleccionar ni reutilizar el ID reservado y Origin/headers no conceden confianza. Para la SPA, el BFF cookie-only usa login de usuario, sesión opaca hash-only almacenada en el backend, cookie host-only Secure/HttpOnly/SameSite=Lax y CSRF en X-Nimo-CSRF-Token; no guarda ni entrega el OAuth token al browser. Sus rutas no aparecen en OpenAPI ni en los SDK.
PKCE obligatorio
code_challenge_method debe ser S256. No se acepta plain. El code_verifier se valida contra el code_challenge con SHA-256.
Registro dinámico (DCR)
POST /oauth/register acepta:
client_name— nombre visible de la appredirect_uris— array de URIs válidastoken_endpoint_auth_method—client_secret_basic,client_secret_postonone
Para none, se guarda isConfidential=false y clientSecretHash=null; no se genera ni devuelve un secreto de cliente.
Solo se aceptan https:// y loopback http://127.0.0.1:{port} / http://[::1]:{port} (RFC 8252).
Validación de redirect_uri
- Clientes registrados: coincidencia exacta contra
redirectUris - Códigos de autorización:
/oauth/tokenrequiere la mismaredirect_uriexacta usada en/oauth/authorize; omitirla o cambiarla rechaza el canje. - Los códigos se consumen con una actualización condicional atómica para impedir canjes concurrentes/repetidos; PKCE S256 sigue siendo obligatorio para clientes públicos y confidenciales.
Refresh tokens
POST /oauth/token con grant_type=refresh_token renueva el access token y (opcionalmente) rota el refresh token. Los refresh tokens son opacos (SHA-256).
Autorizaciones conectadas
GET /oauth/authorizations devuelve la lista de autorizaciones (tokens OAuth activos) emitidas para la empresa del usuario autenticado. Solo incluye filas vigentes: las revocadas y las que ya expiraron quedan fuera. Cada entrada incluye:
id— identificador de la fila de token dentro de la autorizaciónclientName— nombre de la aplicación clienteclientId— identificador público del clienteuserId— usuario que autorizó el tokenoperations— lista de operaciones concedidas (p.ej.documents:read)createdAt— fecha de emisiónlastUsedAt— último usoexpiresAt— fecha de expiración
POST /oauth/authorizations/:id/revoke revoca la autorización completa de ese cliente para ese usuario en la empresa autenticada. Como la rotación de refresh token crea una fila nueva en cada renovación, la revocación no se limita a la fila indicada: corta todas las filas vivas de la misma autorización, así que un id previo a una rotación también desconecta al agente. Los tokens de acceso y refresh quedan invalidados inmediatamente y la revocación surte efecto en la siguiente solicitud del agente. La operación es idempotente.
Audiencia (RFC 8707)
Los access tokens son opacos nbt_ (no JWT), por lo que no llevan un claim aud. El servidor guarda el client_id junto al token y aplica la política de recurso en su estrategia. Para el canal interno de Nimo, esa política exige el ID confidencial allowlisted.
Constantes de tiempo
| Token | Vida | Configurable |
|---|---|---|
| Código de autorización | 10 minutos | Hardcoded |
| Access token | 1 hora | OAUTH_ACCESS_TOKEN_TTL_MS (default 3600000) |
| Refresh token | 30 días | OAUTH_REFRESH_TOKEN_TTL_MS (default 2592000000) |
Los access tokens del scope interno aplican un límite adicional de 15 minutos, incluso si el TTL OAuth global está configurado por encima de ese valor.
Material criptográfico
- Códigos de autorización: 32 bytes aleatorios → hex, hash SHA-256 para un solo uso
- Access tokens: 32 bytes aleatorios en un bearer opaco
nbt_y hash SHA-256 en base de datos - Refresh tokens: 32 bytes aleatorios → hex, hash SHA-256
- Secretos de cliente: 32 bytes aleatorios → hex, hash SHA-256
Relacionado
- Autenticación — Login de usuario y clientes autorizados