Configurer le Custom Token Exchange

Découvrez comment configurer le Custom Token Exchange en associant une Action à un profil de jeton personnalisé.

Pour configurer le Custom Token Exchange pour votre application, vous devez :

• Remplir les conditions préalables
• Activer le Custom Token Exchange pour votre application
• Configurer et gérer un profil d’échange de jeton personnalisé

​

Prérequis

Avant de configurer le Custom Token Exchange, assurez-vous que votre application répond aux prérequis suivants :

• Est une application propriétaire
• Est conforme à OIDC

Pour configurer votre application, accédez à Applications > Advanced Settings > OAuth dans Auth0 Dashboard.

​

Activer Custom Token Exchange pour votre application

Pour activer Custom Token Exchange, créez une nouvelle application ou mettez à jour une application existante dans l’Auth0 Dashboard ou au moyen de la Management API. Vous pouvez créer plusieurs applications pour utiliser Custom Token Exchange.

Lorsque vous créez une nouvelle application :

1. Par défaut, Custom Token Exchange est désactivé. Pour activer Custom Token Exchange, utilisez la Management API pour effectuer un appel POST à Create a Client ou un appel PATCH à Update a Client. Définissez l’attribut allow_any_profile_of_type sous token_exchange à ["custom_authentication"] :

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

2. Activez la connexion que vous voulez utiliser avec Custom Token Exchange pour l’application.
3. Assurez-vous que votre application est définie comme de première partie et qu’elle est configurée pour être conforme à OIDC dans Dashboard > Applications > Advanced Settings > OAuth.

Les bases de données personnalisées avec le mode d’importation ON ne sont prises en charge que pour les opérations setUserById().

Une fois l’application créée, notez le client_id et le client_secret pour les utiliser plus tard lors de l’appel du point de terminaison /oauth/token.

​

Configurer le profil d’échange de jeton personnalisé

Chaque profil d’échange de jeton personnalisé établit une correspondance directe entre un subject_token_type et une Action, qui contient la logique de code propre à un cas d’utilisation précis.

Les requêtes de Custom Token Exchange envoyées au point de terminaison /oauth/token avec une valeur subject_token_type précise sont associées au profil d’échange de jeton personnalisé correspondant, puis acheminées vers l’Action associée pour traitement.

Pour créer un profil d’échange de jeton personnalisé, vous devez :

1. Créer une Action pour le profil
2. Créer le profil d’échange de jeton personnalisé
3. Gérer le profil d’échange de jeton personnalisé

​

Créer une Action pour le profil

Utilisez les objets Event et API de Custom Token Exchange pour écrire une Action qui :

• Décode et valide le subject_token selon le subject_token_type. Vous obtiendrez ainsi des renseignements sur l’utilisateur pour la transaction.
• Applique toute stratégie d’autorisation que vous devez appliquer à la transaction.

Une fois que vous avez la certitude que la transaction peut se poursuivre, définissez l’utilisateur. Auth0 émettra alors des jetons d’accès, d’ID et d’actualisation pour cet utilisateur comme mécanisme d’authentification.

Pour voir des exemples d’Actions de Custom Token Exchange, consultez Example Use Cases and Code Samples.

Une fois votre Action rédigée, ajoutez-la et déployez-la dans Auth0 Dashboard.

1. Accédez à Actions > Library.
2. Sélectionnez Create Action > Build from Scratch.
3. Dans la boîte de dialogue Create Action, saisissez un nom et sélectionnez le déclencheur Custom Token Exchange dans le menu déroulant.

4. Sélectionnez Create.
5. Deploy l’Action.

Après avoir déployé l’Action, copiez l’ID d’Action qu’Auth0 lui a attribué. Vous devez encore ajouter votre logique personnalisée à l’Action. Commencez par récupérer l’ID d’Action pour créer le profil d’échange de jeton personnalisé.

6. Pour obtenir l’ID d’Action dans Auth0 Dashboard, accédez à l’URL de la fenêtre du navigateur. L’ID d’Action devrait correspondre à la dernière partie de l’URL, comme illustré dans l’image suivante :

Vous pouvez également obtenir l’ID d’Action au moyen de la Management API. Commencez par obtenir un jeton de la Management API pour appeler l’API. Ensuite, effectuez la requête GET suivante vers le point de terminaison /actions :

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

Vous devriez recevoir l’id de l’Action dans le corps de la réponse, sous actions[0].id. Vous avez besoin de l’id de l’Action pour créer le profil d’échange de jeton personnalisé.

​

Créer un profil d’échange de jeton personnalisé

Pour créer un profil d’échange de jeton personnalisé, utilisez la Management API pour envoyer une requête POST au point de terminaison /token-exchange-profiles avec les paramètres suivants :

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"
}'

Paramètre	Description
subject_token_type	URI unique du type de jeton de profil commençant par https:// ou urn Les espaces de noms suivants sont réservés et ne peuvent pas être utilisés : http://auth0.com https://auth0.com http://okta.com https://okta.com urn:ietf urn:auth0 urn:okta
action_id	ID de l’Action associée au profil de jeton personnalisé.
type	Doit être défini sur custom_authentication.

Si vous avez créé avec succès un profil d’échange de jeton personnalisé, vous devriez recevoir une réponse semblable à celle-ci :

{
  "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"
}

​

Gérer le profil de Custom Token Exchange

Pour gérer votre profil de Custom Token Exchange, utilisez la Management API pour envoyer des requêtes au point de terminaison /token-exchange-profiles.

Pour obtenir tous vos profils de Custom Token Exchange, envoyez la requête GET suivante au point de terminaison /token-exchange-profiles. Le point de terminaison /token-exchange-profiles prend en charge la pagination avec point de contrôle si vous avez plusieurs profils.

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

Pour mettre à jour le nom ou le subject_token_type d’un profil existant, envoyez la requête PATCH suivante au point de terminaison /token-exchange-profiles.

Une fois l’Action créée, vous ne pouvez plus modifier l’ID de l’Action.

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"
}'

Pour supprimer un profil de Custom Token Exchange, envoyez la requête DELETE suivante au point de terminaison /token-exchange-profiles :

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