Saltar al contenido principal

Token opaco (Opaque token)

Durante el proceso de autenticación, si no se especifica un recurso, Logto emitirá un token de acceso opaco en lugar de un JWT. El token opaco es una cadena aleatoria y es mucho más corto que un JWT:

{
  "access_token": "some-random-string", // token opaco
  "expires_in": 3600,
  "id_token": "eyJhbGc...aBc", // JWT
  "scope": "openid profile email",
  "token_type": "Bearer"
}

El token opaco puede usarse para llamar al endpoint userinfo y para acceder a recursos protegidos que requieren autenticación. Como no es un JWT, ¿cómo puede el servidor de recursos validarlo?

Logto proporciona un endpoint de introspección que puede usarse para validar tokens opacos. Por defecto, el endpoint de introspección es /oidc/token/introspection y acepta solicitudes POST. El siguiente parámetro es obligatorio:

  • token: el token opaco a validar

El endpoint también requiere autenticación del cliente. Puedes usar uno de los siguientes métodos:

  • Autenticación HTTP Basic: Usa el encabezado Authorization con el valor Basic <credenciales-codificadas-en-base64>. Las credenciales deben ser el client ID y el client secret separados por dos puntos (:) y codificados en base64.
  • Autenticación HTTP POST: Usa los parámetros client_id y client_secret:
    • client_id: el client ID de la aplicación que solicitó el token
    • client_secret: el client secret de la aplicación que solicitó el token

El client ID (ID de la app) y el client secret (secreto de la app) pueden ser las credenciales de cualquier aplicación "web tradicional" o "máquina a máquina" en Logto. El endpoint de introspección devolverá un error si las credenciales son inválidas.

El endpoint de introspección devuelve un objeto JSON con los reclamos (claims) del token:

{
  "active": true, // si el token es válido o no
  "sub": "1234567890", // el sujeto del token (el ID del usuario)
  "acr": "urn:logto:acr:1fa", // nivel de garantía de autenticación, cuando se logra
  "amr": ["pwd"], // métodos de autenticación usados en la interacción
  "auth_time": 1787745600 // cuándo se autenticó el usuario (segundos epoch)
}

Si el token no es válido, el campo active será false y los demás reclamos serán omitidos. Consulta Autenticación step-up para saber cómo validar acr, amr y auth_time. Ten en cuenta que los tokens de acceso JWT estructurados no pueden ser introspectados en /oidc/token/introspection—siempre valida los tokens de acceso JWT localmente contra el JWKS de tu tenant.

Aquí tienes un ejemplo no normativo de la solicitud de introspección:

curl --location \
  --request POST 'https://[tenant-id].logto.app/oidc/token/introspection' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=some-random-string' \
  --data-urlencode 'client_id=1234567890' \
  --data-urlencode 'client_secret=1234567890'

Recuerda reemplazar [tenant-id] por el ID de tu tenant.

Token opaco y organizaciones​

Los tokens opacos pueden usarse para recuperar información de membresía de organización a través del endpoint userinfo. Cuando solicitas el scope urn:logto:scope:organizations, el endpoint userinfo devolverá los reclamos relacionados con la organización del usuario, como organizations (IDs de organización) y organization_data.

Sin embargo, los tokens opacos no pueden usarse como tokens de organización. Los tokens de organización siempre se emiten en formato JWT porque:

  1. Los tokens de organización contienen reclamos específicos de la organización (como organization_id y permisos con alcance) que deben ser validados por los servidores de recursos.
  2. El formato JWT permite a los servidores de recursos verificar el token y extraer el contexto de la organización sin llamadas API adicionales.

Para obtener un token de organización, necesitas usar el flujo de refresh token o el flujo de client credentials con parámetros de organización.