Intercambio de tokens On-Behalf-Of

Aprende a usar el intercambio de tokens On-Behalf-Of (OBO) para permitir que los servicios de nivel intermedio conserven la identidad y los permisos del usuario al llamar a APIs posteriores.

El intercambio de tokens On-Behalf-Of (OBO) (RFC 8693) permite que los servicios de nivel intermedio conserven la identidad y los permisos del usuario al llamar a APIs posteriores.

Cuando una aplicación necesita llamar a una API posterior, puede usar:

• Flujo de credenciales de cliente: La aplicación actúa en su propio nombre y se autentica como tal. La solicitud puede haber sido iniciada por un usuario, pero ese contexto se perderá. El servicio posterior solo conoce la identidad de la aplicación que realiza la llamada.
• Intercambio de tokens On-Behalf-Of (OBO): La aplicación recibe un token con alcance de usuario y puede intercambiarlo por un token nuevo para llamar a servicios posteriores. Esto conserva la identidad y el contexto del usuario final original a lo largo de toda la cadena de llamadas.

Por ejemplo, si un usuario inicia una llamada al Servicio A y este luego llama al Servicio B, el intercambio de tokens OBO permite que el Servicio A intercambie el token de acceso del usuario por un token nuevo que:

• Mantiene la identidad y los permisos del usuario original
• Tiene alcances específicos para el Servicio B
• Permite que el Servicio B tome decisiones de autorización basadas en el usuario final

Los intercambios de tokens OBO activan el trigger post-login de Actions, donde:

• El event.transaction.protocol se establece en oauth2-token-exchange.
• El event.transaction.actor registra la cadena de delegación completa.

Al igual que en un flujo de inicio de sesión estándar, los alcances que se devuelven para las llamadas a APIs posteriores se basan en las políticas de Role-Based Access Control (RBAC) del usuario.

Cuando compras el complemento Auth0 for AI Agents, puedes usar el límite máximo de tasa de la Authentication API de tu nivel de suscripción para los intercambios de tokens OBO. Por ejemplo, si usas Private Cloud 100 RPS, puedes superar el límite de 30 RPS para el intercambio de tokens OBO y aprovechar la capacidad completa de 100 RPS para tus solicitudes de intercambio de tokens OBO. El límite de la Authentication API es compartido y actúa como límite global para todas las solicitudes de la Authentication API, incluidos, en conjunto, los inicios de sesión, las renovaciones de tokens y los intercambios de tokens. Ponte en contacto con tu Technical Account Manager para obtener más información.

​

Casos de uso

Entre los casos de uso habituales del intercambio de tokens OBO se incluyen:

• Servidores MCP que necesitan llamar a API de primera parte en nombre del usuario
• Microservicios que necesitan llamar a servicios posteriores en nombre del usuario

Para permitir que sus aplicaciones llamen a API de terceros en nombre del usuario, use Token Vault.

​

Cómo funciona

El intercambio de tokens OBO permite que los servicios de nivel intermedio intercambien un token de usuario recibido por un nuevo token con alcance para un servicio de nivel inferior. El nuevo token conserva la identidad del usuario original y, al mismo tiempo, rastrea la cadena de servicios implicados en la carga útil del JSON Web Token (JWT).

​

Ejemplo: un servidor MCP llama a una API de primera parte

Un usuario se autentica con Auth0 en una aplicación cliente, que luego llama a un servidor MCP, el cual, a su vez, necesita llamar a una API de primera parte.

​

Paso 1: Autenticación del usuario

Cuando el usuario inicia sesión, Auth0 emite un token de acceso con el alcance del servidor MCP y las siguientes claims en la carga útil del JWT:

{
  "sub": "auth0|user123",
  "aud": "https://mcp-server.example.com",
  "azp": "spa_client_id" // o "client_id" según el dialecto del token
}

Claim	Valor	Descripción
sub	auth0|user123	La identidad del usuario final
aud	https://mcp-server.example.com	Token con alcance para el servidor MCP
azp (o client_id según el perfil del token de acceso)	spa_client_id	La aplicación cliente que solicitó el token

​

Paso 2: Intercambio OBO

Mediante el intercambio de tokens OBO, el servidor MCP presenta el token del usuario a Auth0 y solicita un token de acceso para la API de primera parte con el alcance correspondiente. Auth0 emite un nuevo token de acceso para la API con las siguientes claims:

{
  "sub": "auth0|user123",
  "aud": "https://first-party-api.example.com",
  "azp": "mcp_server_client_id", // o "client_id" según el dialecto del token
  "act": {
    "sub": "mcp_server_client_id",
    "act": {
      "sub": "spa_client_id"
    }
  }
}

Claim	Value	Description
sub	auth0|user123	Se conserva la misma identidad del usuario
aud	https://first-party-api.example.com	Token con alcance para la API de primera parte
azp (o client_id según el perfil del token de acceso)	mcp_server_client_id	Cliente que solicitó el token (el servidor MCP que realizó el intercambio)
act	{"sub": "mcp_server_client_id", "act": {"sub": "spa_client_id"}}	Cadena de delegación que muestra todos los actores implicados

​

El claim act

El claim act (actor) rastrea toda la cadena de delegación. Cada nivel de act representa un servicio de la cadena de llamadas, y el act.sub del nivel más externo identifica al actor actual que realizó el intercambio de tokens.

En nuestro ejemplo:

• act.sub del nivel más externo: mcp_server_client_id (el servidor MCP que acaba de intercambiar el token)
• act.sub anidado: spa_client_id (la aplicación cliente original)

El claim azp debe coincidir con el valor de act.sub del nivel más externo, e identificar el servicio que realizó más recientemente el intercambio de tokens.

Si la API de primera parte llama a otro servicio posterior (https://calendar-api.acme.com), la cadena de delegación se extendería:

{
  "sub": "auth0|user123",
  "aud": "https://calendar-api.acme.com",
  "azp": "first_party_api_client_id",
  "act": {
    "sub": "first_party_api_client_id",
    "act": {
      "sub": "mcp_server_client_id",
      "act": {
        "sub": "spa_client_id"
      }
    }
  }
}

La cadena de delegación está limitada a cinco niveles anidados. El intercambio de tokens OBO fallará si el token de sujeto ya tiene cinco niveles act anidados.

400 Bad Request
{
  "error": "invalid_request",
  "error_description": "Delegation chain (`act` claim) depth exceeds the maximum allowed limit of 4"
}

Almacene en caché los tokens de acceso durante toda su vida útil, en lugar de solicitar uno nuevo para cada llamada a la API. Los tokens de acceso se pueden reutilizar hasta que expiren; repetir los intercambios de tokens desperdicia recursos, aumenta la latencia y puede activar límites de velocidad.

​

Usuario > servidor MCP > flujo de la API

El siguiente diagrama muestra un flujo de intercambio de tokens OBO de extremo a extremo, en el que un servidor MCP invoca una API de primera parte en nombre del usuario:

1. Autenticación del usuario: El usuario se autentica en la aplicación cliente. El Servidor de autorización de Auth0 emite el Token A, con alcance correspondiente al servidor MCP.
2. Solicitud inicial: La aplicación cliente llama al servidor MCP y pasa el Token A en el encabezado Authorization: Bearer.
3. Validación e intercambio de tokens: El servidor MCP recibe el Token A, lo valida y lo envía al endpoint /oauth/token del Servidor de autorización de Auth0. Mediante el intercambio de tokens OBO, el servidor MCP presenta el Token A como subject_token y solicita un nuevo token para la API de primera parte.
4. Emisión del token: El Servidor de autorización de Auth0 emite el Token B. El Token B tiene el mismo sub (id de usuario) que el Token A, pero ahora aud (audiencia) es la API de primera parte.
5. Llamada posterior: El servidor MCP llama a la API de primera parte con el Token B. La API valida el Token B y comprueba que la solicitud se está realizando legítimamente “en nombre del” usuario original.

​

Usuario > API1 > API2 > API3

El siguiente diagrama muestra un flujo integral de una cadena de microservicios que realizan llamadas a servicios posteriores en nombre del usuario:

1. Autenticación del usuario: El usuario se autentica correctamente con una aplicación cliente. El Servidor de autorización de Auth0 emite el Token A, con alcance para API1.
2. Solicitud inicial: La aplicación cliente llama a API1 y envía el Token A en el encabezado Authorization: Bearer.
3. API1 delega en API2: API1 recibe el Token A, lo valida y luego lo envía al endpoint /oauth/token del Servidor de autorización de Auth0. Mediante el intercambio de tokens OBO, API1 presenta el Token A como subject_token y solicita un nuevo token para API2.
4. Emisión del token: El Servidor de autorización de Auth0 concede un nuevo token de acceso, el Token B, a API1. El Token B tiene el mismo sub (ID de usuario) que el Token A, pero ahora el aud (audiencia) es API2.
5. Llamada posterior: API1 realiza una solicitud a API2 con el Token B.
6. API2 delega en API3: API2 recibe el Token B, lo valida y luego lo envía al endpoint /oauth/token del Servidor de autorización de Auth0. Mediante el intercambio de tokens OBO, API2 presenta el Token B como subject_token y solicita un nuevo token para API3.
7. Emisión del token: El Servidor de autorización de Auth0 concede un nuevo token de acceso, el Token C, a API2. El Token C tiene el mismo sub (ID de usuario) que los Tokens A y B, pero ahora el aud (audiencia) es API3.
8. Llamada posterior: API2 realiza una solicitud a API3 con el Token C. API3 valida el Token C y comprueba que la solicitud se realiza legítimamente “en nombre del” usuario original.

​

Requisitos previos

Solo los clientes de API personalizada asociados a un servidor de recursos pueden usar el intercambio de tokens OBO. Un cliente de API personalizada se vincula a un servidor de recursos cuando ambos comparten el mismo identificador.

Los clientes de API personalizada deben cumplir los siguientes requisitos:

• Establezca app_type en resource_server.
• Establezca resource_server_identifier en un servidor de recursos válido; es decir, https://my-api.example.com. Auth0 usa el identificador del servidor de recursos como el parámetro audience en las llamadas de autorización.

Como los clientes de API personalizada son clientes de primera parte, asegúrese de omitir el consentimiento del usuario para las API a las que debe acceder su cliente de primera parte.

​

Crear un cliente de API personalizada

Puede crear un cliente de API personalizada con Auth0 Dashboard o la Management API.

Auth0 Dashboard

Para crear un cliente de API personalizada en Auth0 Dashboard:

1. Vaya a Applications > APIs y seleccione su API de backend.

2. Seleccione Add Application e introduzca un nombre para la aplicación.
3. Seleccione Add.

Una vez que la aplicación se haya creado correctamente, revísela seleccionando Configure Application y, a continuación, desplácese hasta Application Properties. El Application Type es Custom API Client.

Management API

Para crear un cliente de API personalizada con el mismo identificador que su servidor de recursos, haga una solicitud POST al endpoint /api/v2/clients con el siguiente cuerpo de la solicitud:

curl --request POST 'https://{yourDomain}/api/v2/clients' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --data '{
    "name": "Custom API Client",
    "app_type": "resource_server",
    "resource_server_identifier": "https://my-api.example.com"
  }'

Parámetro	Descripción
name	Nombre de su cliente de API personalizada.
app_type	El tipo de aplicación de su cliente de API personalizada. Establézcalo en resource_server.
resource_server_identifier	El identificador único de su cliente de API personalizada. Establézcalo en la audiencia de su servidor de recursos; es decir, https://my-api.example.com.

​

Crear client grant

Debes crear un client grant delegado por el usuario entre el cliente de API personalizada y la API de destino para autorizar el acceso.

Auth0 Dashboard

1. Ve a Applications > Applications y selecciona tu cliente de API personalizada.
2. En API Access, busca tu servidor de recursos (es decir, https://my-api.example.com) y selecciona Edit.
3. En User-Delegated Access, selecciona Grant Access y, a continuación, selecciona los permisos que quieras conceder o Always grant all permissions.
4. Selecciona Save.

Management API

Haz una solicitud POST al endpoint /api/v2/client-grants con el siguiente cuerpo de la solicitud:

curl --location 'https://{yourDomain}/api/v2/client-grants' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "audience": "https://my-api.example.com",
    "scope": [
      "read:item"
    ],
    "subject_type": "user"
  }'

​

Configura el intercambio de tokens OBO

Aprende a configurar tu cliente de API personalizada para usar la concesión de intercambio de tokens OBO.

Auth0 Dashboard

1. Ve a Applications > Applications y selecciona tu cliente de API personalizada.
2. En Token Exchange, activa On-Behalf-Of Token Exchange.
3. Selecciona Save.

Management API

Realiza una solicitud PATCH al endpoint /api/v2/clients/{clientId} con el siguiente cuerpo de la solicitud:

curl --location --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --data '{
    "token_exchange": {
      "allow_any_profile_of_type": ["on_behalf_of_token_exchange"]
    }
  }'

​

Realizar el intercambio de tokens OBO

Para realizar el intercambio de tokens OBO, puede usar auth0-api-js, auth0_api_python o la Authentication API.

Guarde en caché los tokens de acceso durante toda su vigencia, en lugar de solicitar uno nuevo para cada llamada a la API. Los tokens de acceso se pueden reutilizar hasta que expiren; repetir los intercambios de tokens desperdicia recursos, aumenta la latencia y puede desencadenar límites de tasa.

JavaScript

Antes de empezar, asegúrate de haber instalado la biblioteca auth0-api-js y sus dependencias.

Primero, inicializa ApiClient con las credenciales de tu servidor MCP:

import { ApiClient } from '@auth0/auth0-api-js';

const apiClient = new ApiClient({
  domain: 'YOUR_AUTH0_DOMAIN',
  audience: 'YOUR_MCP_SERVER_AUDIENCE',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
});

A continuación, usa el método getTokenOnBehalfOf() para intercambiar tokens:

const result = await apiClient.getTokenOnBehalfOf(accessToken, {
  audience: 'YOUR_DOWNSTREAM_API_AUDIENCE',
  scope: 'read:private',  // Opcional
});

getTokenOnBehalfOf() devuelve un objeto que contiene:

• accessToken: El nuevo token para la API de nivel inferior
• scope: Los alcances otorgados
• expiresIn: Tiempo de expiración del token en segundos

Python

Antes de empezar, asegúrate de haber instalado la biblioteca auth0_api_python y sus dependencias.

Primero, importa las clases necesarias e inicializa ApiClient con las credenciales de tu servidor MCP:

from auth0_api_python import ApiClient, ApiClientOptions

api_client = ApiClient(
    ApiClientOptions(
        domain='YOUR_AUTH0_DOMAIN',
        audience='YOUR_MCP_SERVER_AUDIENCE',
        client_id='YOUR_CLIENT_ID',
        client_secret='YOUR_CLIENT_SECRET',
    )
)

A continuación, use el método get_token_on_behalf_of() para intercambiar tokens:

result = await api_client.get_token_on_behalf_of(
    access_token=access_token,
    audience='YOUR_DOWNSTREAM_API_AUDIENCE',
    scope='read:private'  # Opcional
)

get_token_on_behalf_of() devuelve un diccionario que contiene:

• access_token: El nuevo token para tu API de destino
• scope: Los alcances concedidos
• expires_in: Tiempo de expiración del token en segundos

cURL

Realice una solicitud POST al endpoint /oauth/token con el siguiente cuerpo de la solicitud:

curl --location 'https://YOUR_DOMAIN.us.auth0.com/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "subject_token": "AUTH0_SUBJECT_TOKEN",
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "audience": "https://my-api.example.com"
  }'

Parámetro	Ejemplo	Descripción
grant_type	urn:ietf:params:oauth:grant-type:token-exchange	Obligatorio. Indica al Servidor de autorización que realice un intercambio en lugar de un inicio de sesión estándar.
client_id	<custom_api_client_id>	Obligatorio. El ID único del servicio de nivel intermedio que realiza la solicitud.
client_secret	<custom_api_client_secret>	Opcional. El secreto (o aserción) que se usa para autenticar el propio servicio de nivel intermedio. Puede usar cualquier método de autenticación de cliente; sin embargo, no puede establecer token_endpoint_auth_method en none.
subject_token	<auth0_access_token>	Obligatorio. El token del usuario o cliente que el servicio de nivel intermedio tiene actualmente.
subject_token_type	urn:ietf:params:oauth:token-type:access_token	Obligatorio. Define el formato del subject_token (por ejemplo, un token de acceso frente a un ID Token).
requested_token_type	urn:ietf:params:oauth:token-type:access_token	Obligatorio. Indica qué tipo de token quiere recibir a cambio (normalmente, un token de acceso para la siguiente API).
audience	https://my-api.example.com	Obligatorio. El identificador del servicio de destino que recibirá y validará el token nuevo.
scope	read:data write:data	Opcional. Una lista de permisos específicos solicitados para la llamada al servicio de destino, delimitada por espacios.

Si la operación se realiza correctamente, debería recibir una respuesta como la siguiente:

{
  "access_token": "YOUR_AUTH0_ACCESS_TOKEN",
  "expires_in": 86400,
  "token_type": "Bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

Parámetro	Ejemplo	Descripción
access_token	eyJ...	El token de acceso “nuevo” de Auth0. Es el JWT o la cadena opaca que el servicio de nivel intermedio usará para llamar a la API de nivel inferior.
issued_token_type	urn:ietf:params:oauth:token-type:access_token	Confirma el formato del token devuelto. Coincide con requested_token_type de la solicitud, o es un subconjunto de este.
token_type	Bearer	Especifica el esquema de autenticación del encabezado Authorization. En OBO, es Bearer, a menos que el servicio de nivel intermedio y la API de nivel inferior usen DPoP; en ese caso, se usará DPoP.
expires_in	3600	La vigencia del token en segundos depende de la configuración de la API de nivel inferior. Tenga en cuenta que suele ser menor que la del token de usuario original.
scope	read:data	Los permisos específicos concedidos para el token. Debe habilitar estos permisos mediante una concesión de cliente para acceso delegado por el usuario.

​

Compatibilidad con organizaciones

Cuando un usuario se autentica a través de una organización, el token de acceso incluye el claim org_id. El intercambio de tokens OBO conserva este contexto de organización a lo largo de toda la cadena de delegación.

Cuando Auth0 recibe una solicitud de intercambio de tokens OBO con un token de acceso asociado a una organización, valida lo siguiente:

• Que org_id exista en tu inquilino
• Que el usuario (identificado por sub) sea miembro de esa organización

Si la validación falla, Auth0 rechaza la solicitud de intercambio de tokens. Si se valida correctamente, Auth0 emite un nuevo token de acceso que:

• Contiene el mismo claim org_id que el token original
• Aplica las mismas políticas de RBAC específicas de la organización
• Hace que el contexto de la organización esté disponible en el trigger post-login de Actions mediante la propiedad event.organization