Configurar Custom Token Exchange

Aprenda a configurar Custom Token Exchange asociando una Action a un perfil de token personalizado.

Para configurar Custom Token Exchange en tu aplicación, debes hacer lo siguiente:

• Completar los requisitos previos
• Habilitar Custom Token Exchange en tu aplicación
• Configurar y administrar un perfil personalizado de intercambio de tokens

​

Requisitos previos

Antes de configurar el Custom Token Exchange, asegúrate de que tu aplicación cumpla con los siguientes requisitos:

• Sea un cliente propio
• Sea compatible con OIDC

Para configurar tu aplicación, ve a Applications > Advanced Settings > OAuth en el Auth0 Dashboard.

​

Habilite Custom Token Exchange para su aplicación

Para habilitar Custom Token Exchange, cree una nueva aplicación o actualice una existente mediante Auth0 Dashboard o la Management API. Puede crear varias aplicaciones para usar Custom Token Exchange.

Cuando cree una nueva aplicación:

1. De forma predeterminada, Custom Token Exchange está deshabilitado. Para habilitar Custom Token Exchange, use la Management API para realizar una llamada POST a Create a Client o una llamada PATCH a Update a Client. Establezca el atributo allow_any_profile_of_type de token_exchange en ["custom_authentication"]:

{
  "token_exchange": {
    "allow_any_profile_of_type": ["custom_authentication"]
  }
}

2. Habilite la conexión que quiera usar con Custom Token Exchange para la aplicación.
3. Asegúrese de que su aplicación esté marcada como First-Party y configurada para ser compatible con OIDC en Dashboard > Applications > Advanced Settings > OAuth.

Las bases de datos personalizadas con el modo de importación ON solo son compatibles con operaciones setUserById().

Una vez creada la aplicación, anote el client_id y el client_secret para usarlos más adelante al llamar al endpoint /oauth/token.

​

Configurar el perfil de Custom Token Exchange

Cada perfil de Custom Token Exchange establece una correspondencia uno a uno entre un subject_token_type y una Action, que contiene la lógica de código para un caso de uso específico.

Las solicitudes de Custom Token Exchange enviadas al endpoint /oauth/token con un valor subject_token_type específico se asignarán al perfil de Custom Token Exchange correspondiente y se enrutarán a la Action asociada para su procesamiento.

Para crear un perfil de Custom Token Exchange, debe hacer lo siguiente:

1. Crear una Action para el perfil
2. Crear el perfil de Custom Token Exchange
3. Administrar el perfil de Custom Token Exchange

​

Crear una Action para el perfil

Usa los objetos Event y API de Custom Token Exchange para escribir una Action que:

• Decodifique y valide el subject_token según el subject_token_type. Esto te proporcionará información sobre el usuario para la transacción.
• Aplique cualquier política de autorización que necesites para la transacción.

Una vez que confirmes que la transacción puede continuar, establece el usuario. Auth0 emitirá entonces tokens de acceso, de ID y de actualización para este usuario como forma de autenticación.

Para ver ejemplos de Actions de Custom Token Exchange, consulta Casos de uso de ejemplo y muestras de código.

Una vez que hayas escrito tu Action, agrégala y despliégala en el Auth0 Dashboard.

1. Ve a Actions > Library.
2. Selecciona Create Action > Build from Scratch.
3. En el cuadro de diálogo Create Action, introduce un nombre y selecciona el trigger Custom Token Exchange en el menú desplegable.

4. Selecciona Create.
5. Haz clic en Deploy para implementar la Action.

Después de desplegar la Action, copia el ID de la Action que Auth0 le haya asignado. Aún tienes que agregar tu lógica personalizada a la Action. Primero, obtén el ID de la Action para crear el perfil personalizado de intercambio de tokens.

6. Para obtener el ID de la Action en el Auth0 Dashboard, ve a la URL de la ventana del navegador. El ID de la Action debe ser la última parte de la URL, como se muestra en la siguiente imagen:

También puedes obtener el ID de la Action mediante la Management API. Primero, obtén un token de la Management API para consumir la API. Luego, realiza la siguiente solicitud GET al endpoint /actions:

curl --location 'https://{yourDomain}/api/v2/actions/actions?actionName={yourActionName}' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \

Deberías recibir el ID de la Action en el cuerpo de la respuesta, dentro de actions[0].id. Necesitas el ID de la Action para crear el perfil personalizado de intercambio de tokens.

​

Crear un perfil personalizado de intercambio de tokens

Para crear el perfil personalizado de intercambio de tokens, use la Management API para realizar una solicitud POST al endpoint /token-exchange-profiles con los siguientes parámetros:

curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "<YOUR_PROFILE_NAME>",
    "subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
    "action_id": "<YOUR_ACTION_ID>",
    "type": "custom_authentication"
}'

Parámetro	Descripción
subject_token_type	URI única del tipo de token de perfil que comienza con https:// o urn Los siguientes espacios de nombres están reservados y no se pueden usar: http://auth0.com https://auth0.com http://okta.com https://okta.com urn:ietf urn:auth0 urn:okta
action_id	ID de la Action asociada al perfil personalizado de intercambio de tokens.
type	Debe establecerse como custom_authentication.

Si creó correctamente un perfil personalizado de intercambio de tokens, debería recibir una respuesta como la siguiente:

{
  "id":"tep_9xqewuejpa2RTltf",
  "name":"<YOUR_PROFILE_NAME>",
  "type":"custom_authentication",
  "subject_token_type":"<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
  "action_id":"<YOUR_ACTION_ID>",
  "created_at":"2025-01-30T13:19:00.616Z",
  "updated_at":"2025-01-30T13:19:00.616Z"
}

​

Administrar el perfil personalizado de intercambio de token

Para administrar su perfil personalizado de intercambio de token, use la Management API para realizar solicitudes al endpoint /token-exchange-profiles.

Para obtener todos sus perfiles personalizados de intercambio de token, realice la siguiente solicitud GET al endpoint /token-exchange-profiles. El endpoint /token-exchange-profiles admite paginación mediante checkpoints si tiene varios perfiles.

curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \

Para actualizar el nombre o el subject_token_type de un perfil existente, realice la siguiente solicitud PATCH al endpoint /token-exchange-profiles.

Una vez creada la Action, no puede modificar su ID.

curl --location --request PATCH 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "external-idp-migration",
    "subject_token_type": "urn:partner0:external-idp-migration"
}'

Para eliminar un perfil de intercambio de Token personalizado, realiza la siguiente solicitud DELETE al endpoint /token-exchange-profiles:

curl --location --request DELETE 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data ''