Skip to content

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étodoRutaDescripción
GET/.well-known/oauth-authorization-serverMetadata del servidor — issuer, endpoints, code_challenge_methods_supported
POST/oauth/registerRegistro dinámico de cliente — rate-limited 5/IP/60s
POST/oauth/authorizeSolicitud de autorización con PKCE S256 obligatorio — rate-limited 20/IP/60s
POST/oauth/tokenCanje de código por token y renovación con refresh — rate-limited 20/IP/60s
GET/oauth/authorizationsLista autorizaciones conectadas de la empresa autenticada
POST/oauth/authorizations/:id/revokeRevoca 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 app
  • redirect_uris — array de URIs válidas
  • token_endpoint_auth_method — client_secret_basic, client_secret_post o none

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/token requiere la misma redirect_uri exacta 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ón
  • clientName — nombre de la aplicación cliente
  • clientId — identificador público del cliente
  • userId — usuario que autorizó el token
  • operations — lista de operaciones concedidas (p.ej. documents:read)
  • createdAt — fecha de emisión
  • lastUsedAt — último uso
  • expiresAt — 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 ​

TokenVidaConfigurable
Código de autorización10 minutosHardcoded
Access token1 horaOAUTH_ACCESS_TOKEN_TTL_MS (default 3600000)
Refresh token30 díasOAUTH_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 ​