@adonisjs/sesame: servidor OAuth 2.1 y OpenID Connect integrado en AdonisJS con soporte para agentes MCPArtículo · digest del 21 de noviembre
Candado de latón con el grabado SESAME y una llave de acceso verde brillante sobre fondo oscuro
Artículo4 secciones≈ 11 min

@adonisjs/sesame: servidor OAuth 2.1 y OpenID Connect integrado en AdonisJS con soporte para agentes MCP

El 20 de noviembre de 2026, el equipo de AdonisJS lanzó el paquete oficial @adonisjs/sesame v0.11, un servidor OAuth 2.1 y OpenID Connect integrado. La ventaja principal del lanzamiento en el blog del framework es clara: el paquete se despliega en dos comandos, no se adueña de tus usuarios ni de tus pantallas de acceso, y permite dar entrada segura a la API a servicios de terceros, herramientas CLI y agentes de IA mediante el protocolo MCP.

Los tokens de acceso habituales en AdonisJS funcionan muy bien mientras solo tu propio frontend habla con el backend. En cuanto piden acceso integraciones externas o agentes de IA, todo cambia: no puedes entregarles tu contraseña, abrir acceso total da miedo y el usuario debe conservar un botón para «desconectar todo». Para eso existe OAuth. Sin embargo, como señaló con acierto el autor del paquete Julien Ripouteau, «OAuth en sí no es difícil de entender, pero es muy fácil equivocarse sin darse cuenta»: un pequeño descuido al validar redirect_uri, rotar tokens o revocar permisos se convierte rápido en una brecha.

Banner oficial del lanzamiento de @adonisjs/sesame, servidor OAuth 2.1 y OpenID Connect para AdonisJS (Fuente: blog de AdonisJS)

@adonisjs/sesame sigue estrictamente OAuth 2.1, así que elimina de raíz los flujos peligrosos de OAuth 2.0: no incluye implicit grant ni password grant, y PKCE (S256) es obligatorio para cada cliente. En palabras simples, PKCE es un secreto de un solo uso junto con su hash SHA-256; sin él, un código de autorización interceptado no sirve para obtener un token. También incluye de serie OpenID Connect (ID tokens, UserInfo, discovery), client_credentials para llamadas entre servicios, introspección y revocación de tokens, además de poder elegir entre tokens opacos o JWT con rotación de claves.

Instalación y guard oauth con seguridad de tipos

No hace falta levantar un microservicio aparte: las tablas de clientes, grants y tokens se crean directo en tu base de datos con Lucid o Kysely (--store=kysely).

# Instalación con Lucid (para Kysely agrega la bandera --store=kysely)
node ace add @adonisjs/sesame
node ace migration:run

Junto al guard session aparece el guard oauth. Los scopes se infieren desde la configuración mediante InferScopes<typeof sesameConfig> y declare module '@adonisjs/sesame/types', así que cualquier error tipográfico en el nombre de un permiso se detecta al compilar TypeScript.

// Protección de ruta mediante el guard oauth con verificación de scope
router.get('/api/me', async ({ auth }) => {
  const guard = auth.use('oauth')
  const user = await guard.authenticate()

  if (!guard.hasScope('read')) {
    throw guard.insufficientScopeError(['read'])
  }

  return { id: user.id, clientId: guard.clientId }
})

Sin un token válido, la API responde 401; sin el scope necesario, devuelve 403 con la cabecera WWW-Authenticate indicando los permisos faltantes. En start/kernel.ts también tienes listos los middlewares scopes y anyScope.

El protocolo por un lado, la interfaz por otro

Sesame no controla tu tabla de usuarios ni renderiza HTML: las cuentas, el login y el formulario de consentimiento siguen siendo tuyos. En config/sesame.ts defines la URL del servidor, el almacén, los scopes y las rutas de tus vistas.

// Configuración básica del servidor en config/sesame.ts
const sesameConfig = defineConfig({
  issuer: env.get('APP_URL'),
  store: stores.lucid(),
  scopes: { read: 'Read access', write: 'Write access' },
  defaultScopes: ['read'],
  loginPage: '/login',
  consentPage: '/oauth/consent',
})

Si el usuario no ha iniciado sesión, Sesame lo redirige a /login con el parámetro authorization_query; tras autenticarse, tu controlador lo devuelve a /oauth/authorize con los mismos parámetros. Si ya aprobó esos permisos antes, se omite la pantalla de consentimiento. De lo contrario, el navegador recibe un auth_token con el que el controlador recupera la solicitud desde el servidor.

export default class OAuthConsentController {
  async show({ auth, request, response, view }: HttpContext) {
    const user = await auth.authenticate()
    const authToken = request.input('auth_token')

    // Tomamos los datos desde el servidor y no desde la query string
    const pending = await sesame.findPendingAuthorizationRequest({
      token: authToken,
      userId: String(user.id),
    })
    if (!pending) return response.badRequest('Запрос истёк.')

    const client = await sesame.findClient(pending.clientId)
    if (!client) return response.badRequest('Клиент не найден.')

    return view.render('oauth/consent', {
      authToken,
      clientName: client.name,
      scopes: pending.scopes.map((scope) => ({
        name: scope,
        description: sesame.config.scopes[scope] ?? scope,
      })),
    })
  }
}

Leer desde el servidor protege contra la manipulación de la URL: un atacante no podrá inyectar en la barra de direcciones el nombre de otra aplicación ni una lista recortada de permisos. El formulario en Edge envía POST /oauth/consent con {{ csrfField() }} y auth_token, permite aprobar solo parte de los scopes mediante el campo scope y, al llamar manualmente a sesame.approveAuthorization({ authToken, userId, context: { teamId } }), adjunta cualquier contexto al grant para leerlo luego desde auth.use('oauth').context.

Grants y defensa contra el robo del refresh token

En lugar de dejar llaves sueltas por todas partes, cada consentimiento crea un grant: un registro único con los permisos otorgados al cliente, al que quedan atados todos los códigos y tokens. La pantalla de «Aplicaciones conectadas» se resuelve con dos llamadas:

// Lista de grants activos y revocación conjunta de todos los tokens del cliente
const grants = await sesame.listGrants({ userId: String(user.id) })
await sesame.revokeGrant({ grantId, userId: String(user.id) })

Sobre los grants también se apoya la rotación de refresh tokens con replay detection. Cada vez que se renueva el acceso, el refresh token anterior queda invalidado. Si un atacante lo robó e intenta enviarlo de nuevo, Sesame anula de inmediato todo el grant completo: dejan de funcionar absolutamente todos los tokens de esa cadena.

Maqueta interactiva: panel de grants y disparo de replay detection

Haz clic en los botones de arriba: rota el token e intenta reenviar el rt_v1 caducado. Así mismo reacciona el servidor real: un solo reintento sospechoso cierra toda la sesión al instante.

Soporte nativo de MCP y estado de la versión 0.11

Los clientes MCP se conectan sin registro manual en un panel de administración: reciben un 401, descubren el servidor de autorización, se identifican, completan PKCE y repiten la petición con un Bearer token. En Sesame todo esto se habilita con una sola llamada:

// Registro de un recurso MCP protegido con autodescubrimiento
sesame.registerProtectedResource({
  resource: '/api/mcp',
  scopes: ['read', 'write'],
})

Esta llamada levanta Protected Resource Metadata (RFC 9728) para descubrir el servidor desde la respuesta 401, Resource Indicators (RFC 8707) para atar el token a una única API (audience), sugerencias de scopes en WWW-Authenticate, además de Dynamic Client Registration (DCR) y Client ID Metadata Documents para que un cliente MCP se presente mediante un documento en una URL pública. Todos los detalles están en la documentación de OAuth Server en AdonisJS.

Eso sí, no conviene meter esta maquinaria en cualquier proyecto: si solo tienes tu propio frontend o app móvil sin clientes externos ni MCP, las sesiones estándar o el guard access_tokens son más que suficientes. Además, el paquete exige AdonisJS 7, Node.js 24+ y @adonisjs/auth; en la versión 6 del framework no funcionará sin actualizar.

Para quienes ya usaban el paquete bajo su nombre anterior @julr/sesame, la migración es directa porque la API, la configuración y el esquema de base de datos no cambiaron. La advertencia clave de la guía de migración es no ejecutar node ace add @adonisjs/sesame sobre una instalación previa, ya que duplicará configuraciones y migraciones. Desinstala el paquete viejo, instala el nuevo con tu gestor de paquetes y actualiza los imports (y si vienes de una versión anterior a 0.8, sube primero a 0.8). Ahora salió la versión preliminar 0.11; antes de lanzar la 1.0, el equipo realiza una revisión final de la API pública y espera comentarios en GitHub.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 4