Intercambio de tokens de acceso con Token Vault

Aprenda cómo una aplicación puede acceder a Token Vault para intercambiar un token de acceso de Auth0 por un token de acceso para llamar a API externas.

Token Vault admite el intercambio de tokens de acceso, que permite a una aplicación cliente intercambiar un token de acceso de Auth0 (token de sujeto) por el token de acceso de un proveedor externo (token solicitado).

Cuando una aplicación de página única (SPA) llama a una API de backend, solo envía un token de acceso de Auth0 en el encabezado Authorization. Como la API de backend no recibe ningún token de actualización emitido para la SPA, no puede usar el intercambio de token de actualización para acceder a Token Vault y llamar a API externas.

En su lugar, la API de backend puede intercambiar el token de acceso de Auth0 recibido de la SPA por el token de acceso de un proveedor externo; esto es lo que se conoce como intercambio de tokens de acceso. Este proceso mantiene seguras en el backend las credenciales externas confidenciales.

En el intercambio de tokens de acceso de Auth0, la API de backend actúa tanto como cliente como Servidor de autorización:

• Cliente: Usa sus propias credenciales para realizar de forma segura el intercambio de tokens de acceso con el Servidor de autorización de Auth0. En Auth0, se crea un Custom API Client con el mismo identificador que la API de backend. La API de backend pasa las credenciales del Custom API Client para realizar de forma segura el intercambio de tokens de acceso con el Servidor de autorización de Auth0.
• Servidor de recursos: Expone la API de backend a la SPA y valida el token de acceso de Auth0.

Al actuar como intermediaria entre la SPA y el Servidor de autorización de Auth0, la API de backend evita que clientes no autorizados roben el token de Auth0 y lo usen para acceder al proveedor externo en nombre del usuario.

​

Casos de uso

Entre los casos de uso más comunes del intercambio de tokens de acceso se incluyen:

• Una API de backend: un usuario interactúa con una SPA, que luego llama a una API de backend para intercambiar un token de acceso de Auth0 por un token de acceso de un proveedor externo con el Servidor de autorización de Auth0.
• Arquitectura de microservicios: servicios de backend, como servidores MCP u otros servidores de recursos de OAuth 2.0, que necesitan intercambiar tokens de acceso para acceder a API externas.

​

Cómo funciona

El siguiente diagrama de secuencia describe de principio a fin cómo llamar a API externas mediante el intercambio de tokens de acceso en Auth0:

Veamos un ejemplo real: un usuario quiere programar una reunión en Google Calendar desde una SPA.

​

Requisitos previos

Antes de empezar, debes configurar el intercambio de tokens de acceso con Token Vault.

​

Paso 1: Conectar y autorizar el acceso

Para programar la reunión, la SPA debe conectarse a Google mediante Auth0 y luego obtener el permiso del usuario para acceder a la API de Google Calendar. El usuario inicia sesión en la aplicación con Google mediante el flujo Connected Accounts, que usa la My Account API. Si la aplicación usa Organizaciones, el usuario inicia sesión en la organización de destino antes de continuar.

Después de que la My Account API valida y completa la solicitud de Connected Accounts, almacena los tokens de acceso y de actualización de Google con los alcances de calendario solicitados en Token Vault.

​

Paso 2: La SPA llama a la API de backend con el token de acceso de Auth0

Cuando la SPA llama a la API de backend, envía el token de acceso de Auth0 en el encabezado Authorization a la API de backend. La API de backend valida el token de acceso de Auth0 comprobando lo siguiente:

• Firma: Verifica la firma del token con la clave pública de Auth0. Esto confirma que Auth0 emitió el token de acceso.
• Emisor: Comprueba el claim iss en el payload del token para confirmar que el token fue emitido por tu inquilino de Auth0.
• Audiencia: Comprueba el claim aud para asegurarse de que coincida con el identificador único de la propia API de backend. Esto confirma que el token se emitió específicamente para este servidor de recursos.
• Expiración: Valida el claim exp para asegurarse de que el token siga siendo válido y no haya expirado.
• Scopes: Comprueba el claim scope para determinar qué permisos se le han concedido al usuario.

Después de completar correctamente estas comprobaciones, la API de backend puede confiar en el token de acceso de Auth0 y continuar con el intercambio de tokens.

​

Paso 3: La API de backend realiza el intercambio de tokens de acceso

Para realizar el intercambio de tokens de acceso, debe crear un Custom API Client vinculado a la API de backend. El Custom API Client tiene el mismo identificador que su API de backend y tiene habilitado el tipo de concesión de Token Vault.

Cuando la API de backend realiza el intercambio de tokens de acceso, se autentica pasando las credenciales del Custom API Client al Servidor de autorización de Auth0, lo que demuestra que es la misma entidad que se registró en el Auth0 Dashboard.

Para realizar el intercambio de tokens de acceso, la API de backend usa los SDK de Auth0 para enviar una solicitud POST al endpoint /oauth/token.

En la solicitud de token, la API de backend:

• Pasa las credenciales de cliente de la API de backend (las del Custom API Client) al Servidor de autorización de Auth0 para autenticarse.
• Intercambia un token de acceso de Auth0 por un token de acceso de Google.

curl --request POST 'https://{yourDomain}/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<YOUR_CUSTOM_API_CLIENT_ID>",
    "client_secret": "<YOUR_CUSTOM_API_CLIENT_SECRET>",
    "subject_token": "<YOUR_AUTH0_ACCESS_TOKEN>",
    "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
    "connection": "google-oauth2"
  }'

Parámetro	Descripción
grant_type	El tipo de concesión. Para Token Vault, configúralo en urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_id	ID de la aplicación cliente
client_secret	Secreto del cliente. Nota: Puedes usar cualquier método de autenticación de cliente para obtener el token de acceso de un proveedor externo.
subject_token_type	Tipo de token de sujeto. Para el intercambio de tokens de acceso, configúralo con el token de acceso: urn:ietf:params:oauth:token-type:access_token.
subject_token	El token de acceso de Auth0 que el Servidor de autorización de Auth0 valida para identificar al usuario.
requested_token_type	El tipo de token solicitado. Para Token Vault, configúralo con el token de acceso del proveedor externo o http://auth0.com/oauth/token-type/federated-connection-access-token
connection	El nombre de la conexión, en este caso, google-oauth2.
login_hint	(Opcional) Usa login_hint solo si el usuario tiene varias cuentas de la misma conexión, como una cuenta de Google del trabajo y una cuenta personal de Google. Cuando proporcionas un valor para login_hint durante el intercambio de tokens, indicas explícitamente a cuál de las varias cuentas vinculadas del usuario corresponde la solicitud.

​

Paso 4: El Servidor de autorización de Auth0 valida el token de acceso

El Servidor de autorización de Auth0 valida y carga el perfil del usuario asociado al token de acceso de Auth0:

• Auth0 verifica que el cliente que realiza la solicitud de intercambio de tokens de acceso esté vinculado a la API de backend identificada por la audience del token de acceso.
• Auth0 comprueba si el array connected_accounts del perfil del usuario contiene una cuenta de usuario con el nombre de la conexión indicado en la solicitud de autorización.
• Si la solicitud de autorización contiene login_hint, Auth0 busca una identidad que coincida tanto con el nombre de la conexión como con login_hint.
• Si Auth0 no puede encontrar al usuario, devuelve un código de estado 401 con un mensaje de error.

Una vez que el Servidor de autorización de Auth0 valida al usuario, localiza el token de acceso de Google en Token Vault. Si sigue siendo válido, Auth0 devuelve el token de acceso de Google con sus alcances y su hora de expiración:

{
  "access_token": "<YOUR_GOOGLE_ACCESS_TOKEN>",
  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.addons.execute https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.events.readonly https://www.googleapis.com/auth/calendar.settings.readonly https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid",
  "expires_in": 1377,
  "issued_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "token_type": "Bearer"
}

Con el token de acceso de Google, la API de backend llama a la API de Google Calendar en nombre del usuario para programar la reunión.