Appeler votre API à l’aide du flux Custom Token Exchange

Découvrez comment appeler votre API à l’aide du flux Custom Token Exchange.

Pour utiliser Custom Token Exchange, envoyez une requête POST au point de terminaison /oauth/token avec les paramètres suivants :

N’oubliez pas que les jetons de sujet et d’acteur utilisés avec Custom Token Exchange peuvent être de n’importe quel format ou type, tant que le code de votre Action peut les interpréter. Vous devez mettre en place une validation rigoureuse des jetons que vous recevez et acceptez. Si vous ne le faites pas, vous vous exposez à différents vecteurs d’attaque, comme l’usurpation ou les attaques par rejeu, ce qui pourrait permettre à des acteurs malveillants de s’authentifier avec l’identifiant utilisateur de quelqu’un d’autre ou d’agir en son nom sans autorisation.

Chaque subject_token_type correspond à un profil Custom Token Exchange et est associé à une Action qui sera exécutée pour gérer cette transaction.

Paramètre	Description
grant_type	Pour Custom Token Exchange, utilisez urn:ietf:params:oauth:grant-type:token-exchange.
subject_token_type	Le type du jeton de sujet. Pour Custom Token Exchange, il peut s’agir de n’importe quel URI relevant de votre propre espace de noms, comme http://acme.com/legacy-token ou urn:acme:legacy-token. 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
subject_token	Le jeton de sujet, que votre Action doit valider et utiliser pour identifier l’utilisateur.
client_id	L’ID client de l’application que vous utilisez pour l’échange de jetons. Comme pour les autres types d’octroi, vous pouvez aussi transmettre l’ID client dans l’en-tête Authorization à l’aide de HTTP Basic Auth.
client_secret	Le secret client de l’application que vous utilisez pour l’échange de jetons. Comme pour les autres types d’octroi, vous pouvez aussi transmettre le secret client dans l’en-tête Authorization à l’aide de HTTP Basic Auth. D’autres options sont également offertes, comme expliqué dans la documentation de référence de l’Authentication API d’Auth0. Notez que Custom Token Exchange peut être utilisé par des applications publiques. Assurez-vous de lire Protection contre les attaques dans ce cas.
audience	L’identifiant de l’API défini dans Auth0. L’audience par défaut du locataire sera utilisée si ce paramètre n’est pas présent, conformément à la configuration dans les Paramètres du locataire.
scope	(Facultatif) Le paramètre scope OAuth2.
organization	(Facultatif) L’identifiant de l’organisation à laquelle vous souhaitez associer la requête. Vous pouvez aussi préciser un nom d’organisation si Utiliser les noms d’organisation dans l’Authentication API est autorisé pour votre locataire. Pour en savoir plus sur le traitement de la requête, consultez la méthode d’API api.authentication.setOrganization().
actor_token	(Facultatif) Un jeton identifiant l’acteur ou le principal qui effectue une délégation au nom de l’utilisateur sujet. Doit être fourni avec actor_token_type.
actor_token_type	(Facultatif) Le type du jeton d’acteur. Doit être fourni avec actor_token. Pour les jetons d’identité Auth0, utilisez urn:ietf:params:oauth:token-type:id_token pour une validation automatique côté serveur. Pour les autres valeurs, appliquez les mêmes restrictions d’espace de noms que pour subject_token_type.

Lorsqu’un acteur est défini pour la transaction, aucun jeton d’actualisation n’est émis, peu importe les scopes demandés. Le scope offline_access est exclu de la réponse. C’est intentionnel : les jetons délégués ne doivent pas survivre à l’échange immédiat, ce qui garantit que chaque demande d’accès subséquente passe par la logique d’autorisation de la CTE Action afin de valider de nouveau la délégation.

Votre CTE Action doit valider le actor_token de façon sécuritaire en appliquant la même rigueur (par exemple, la vérification de la signature cryptographique) que pour le subject_token. Lorsque actor_token_type est urn:ietf:params:oauth:token-type:id_token, Auth0 effectue cette validation automatiquement.

Les autres paramètres d’extension non répertoriés ci-dessus sont inclus dans le champ event.request.body de l’Action correspondante.

​

Exemple de requête

curl --location 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'audience=https://api.acme.com' \
--data-urlencode 'scopes=openid offline_access acme-scope1 acme-scope2' \
--data-urlencode 'subject_token_type=urn:acme:external-idp-migration' \
--data-urlencode 'subject_token=t8e7S2D9trQm73e .... iqBR3GjxDtbDVjpfQU' \
--data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
--data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'
--data-urlencode 'organization=periscope-acme'

​

Exemple de requête avec un jeton d’acteur

Lors d’un échange d’autorisation délégué, incluez actor_token et actor_token_type :

curl --location 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'audience=https://api.acme.com' \
--data-urlencode 'scopes=openid acme-scope1 acme-scope2' \
--data-urlencode 'subject_token_type=urn:acme:legacy-token' \
--data-urlencode 'subject_token=t8e7S2D9trQm73e .... iqBR3GjxDtbDVjpfQU' \
--data-urlencode 'actor_token=eyJhbGciOiJSUzI1NiI .... kXdF9tZ3c' \
--data-urlencode 'actor_token_type=urn:ietf:params:oauth:token-type:id_token' \
--data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
--data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'