Configurer l’échange de jetons personnalisé

Découvrez comment configurer l’échange de jetons personnalisé en associant une Action à un profil de jetons personnalisé.

Pour configurer l’échange de jetons personnalisé pour votre application, vous devez :

• Remplir les conditions préalables
• Activer l’échange de jetons personnalisé pour votre application
• Configurer et gérer un profil d’échange de jetons personnalisé

​

Prérequis

Avant de configurer l’Échange de jetons personnalisé, assurez-vous que votre application remplit les prérequis suivants :

• Est un client de première partie
• Est conforme à OIDC

Pour configurer votre application, accédez à Applications > Paramètres avancés > OAuth dans l’Auth0 Dashboard.

​

Activer l’échange de jetons personnalisé pour votre application

Pour activer l’échange de jetons personnalisé, créez une nouvelle application ou mettez à jour une application existante à l’aide de l’Auth0 Dashboard ou de la Management API. Vous pouvez créer plusieurs applications pour utiliser l’échange de jetons personnalisé.

Lorsque vous créez une nouvelle application :

1. Par défaut, l’échange de jetons personnalisé est désactivé. Pour activer l’échange de jetons personnalisé, utilisez la Management API pour effectuer une requête POST à Créer un client ou une requête PATCH à Mettre à jour un client. Définissez l’attribut allow_any_profile_of_type sous token_exchange sur ["custom_authentication"] :

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

2. Activez la connexion que vous souhaitez utiliser avec l’échange de jetons personnalisé pour l’application.
3. Assurez-vous que votre application est définie comme First-Party et qu’elle est configurée pour être conforme à OIDC dans Dashboard > Applications > Advanced Settings > OAuth.

Les bases de données personnalisées dont le mode d’importation est réglé à 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 lorsque vous appellerez le point de terminaison /oauth/token.

​

Configurer profil d’échange de jetons personnalisé

Chaque profil d’échange de jetons personnalisé établit une correspondance biunivoque entre un subject_token_type et une Action, qui contient la logique de code pour un cas d’utilisation précis.

Les requêtes échange de jetons personnalisé envoyées au endpoint /oauth/token avec une valeur subject_token_type précise seront associées au Custom Token Profile correspondant et acheminées vers l’Action associée pour traitement.

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

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

​

Créer une Action pour le profil

Utilisez les objets Event et API de échange de jetons personnalisé 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 politique d’autorisation nécessaire à 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 dans le cadre de l’authentification de l’utilisateur.

Pour voir des exemples d’Actions de échange de jetons personnalisé, consultez Exemples de cas d’utilisation et échantillons de code.

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

1. Accédez à Actions > Library.
2. Sélectionnez Create Action > Build from Scratch.
3. Dans la boîte de dialogue Create Action, entrez un nom et sélectionnez le Trigger échange de jetons personnalisé dans la liste déroulante.

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

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

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

Vous pouvez aussi obtenir l’Action ID au moyen de la Management API. Commencez par obtenir un Management API Token pour appeler l’API. Ensuite, envoyez la requête GET suivante au endpoint /actions :

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

Vous devriez trouver l’Action ID dans le corps de la réponse, à actions[0].id. Vous aurez besoin de l’Action ID pour créer le Profil d’échange de jetons personnalisé.

​

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

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

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 vous ne pouvez pas les utiliser : 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 d’échange de jetons personnalisé.
type	Doit être défini sur custom_authentication.

Si vous avez créé un profil d’échange de jetons personnalisé avec succès, vous devriez recevoir une réponse semblable à la suivante :

{
  "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 d’échange de jetons personnalisé

Pour gérer votre profil d’échange de jetons personnalisé, utilisez la Management API pour envoyer des requêtes au point de terminaison /token-exchange-profiles.

Pour obtenir tous vos profils d’échange de jetons personnalisés, 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 par checkpoint 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, effectuez la requête PATCH suivante à l’endpoint /token-exchange-profiles.

Une fois l’Action créée, vous ne pouvez pas modifier l’Action 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"
}'

Pour supprimer un profil d’échange de jetons personnalisé, effectuez 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 ''