Obtenir un jeton

L’échange de jetons On-Behalf-Of (OBO) permet à un service intermédiaire d’échanger un jeton utilisateur entrant contre un nouveau jeton destiné au service en aval.

POST /oauth/token

L’échange de jetons On-Behalf-Of (OBO) (RFC 8693) permet aux services intermédiaires d’échanger un jeton utilisateur contre un nouveau jeton pour appeler des services en aval.

Le nouveau jeton conserve l’identité et les permissions de l’utilisateur d’origine tout en étant limité au service en aval, ce qui permet à ce service de prendre des décisions d’autorisation en fonction de l’utilisateur final. La chaîne de délégation est consignée dans la revendication act (acteur), chaque niveau représentant un service dans la chaîne d’appels. Pour en savoir plus, consultez la documentation sur l’échange de jetons On-Behalf-Of.

​

Remarques

• Seuls les clients d’API personnalisés associés à un serveur de ressources peuvent utiliser l’échange de jetons OBO. Un client d’API personnalisé doit respecter les exigences suivantes :

  • Définissez app_type sur resource_server.
  • Définissez resource_server_identifier sur un serveur de ressources valide, c.-à-d. https://my-api.example.com. Auth0 utilise l’identifiant du serveur de ressources comme paramètre audience dans les requêtes d’autorisation.

• Les scopes émis pour l’application peuvent différer des scopes demandés. Dans ce cas, un paramètre scope sera inclus dans la réponse JSON. Les scopes sont basés sur les politiques de contrôle d’accès basé sur les rôles (RBAC) de l’utilisateur.

• Les échanges de jetons OBO déclenchent le déclencheur d’Action post-login, dans lequel event.transaction.protocol est défini sur oauth2-token-exchange et event.transaction.actor permet de suivre l’ensemble de la chaîne de délégation.

• La chaîne de délégation est limitée à cinq niveaux imbriqués. L’échange de jetons OBO échoue si le jeton de sujet comporte déjà cinq niveaux act imbriqués.

• Mettez les jetons d’accès en cache pour toute la durée de validité du jeton au lieu de demander un nouveau jeton pour chaque appel d’API. Les jetons d’accès peuvent être réutilisés jusqu’à leur expiration; les échanges de jetons répétés gaspillent des ressources, augmentent la latence et peuvent déclencher des limites de débit.

​

Paramètres

DPoP · string

Une preuve DPoP pour la requête. Ce paramètre est facultatif et n’est requis que si votre application utilise la preuve de possession démontrée.

auth0-forwarded-for · string

L’adresse IP de l’utilisateur final sous forme de chaîne de caractères. Définissez ce paramètre si vous voulez que la protection Limitation du débit des adresses IP suspectes fonctionne dans les scénarios côté serveur.

​

Corps de la requête

grant_type · string · requis

Indique le flux que vous utilisez. Pour l’échange de jetons On-Behalf-Of, utilisez urn:ietf:params:oauth:grant-type:token-exchange.

subject_token_type · string · requis

Le type du jeton de sujet. Pour l’échange de jetons On-Behalf-Of, utilisez urn:ietf:params:oauth:token-type:access_token.

subject_token · string · requis

Le jeton d’accès Auth0 reçu de l’utilisateur ou du service en amont que le service intermédiaire détient actuellement.

requested_token_type · string · requis

Indique le type de jeton que vous souhaitez recevoir. Pour l’échange de jetons On-Behalf-Of, utilisez urn:ietf:params:oauth:token-type:access_token.

client_id · string · requis

L’ID client de votre client d’API personnalisé. Le client d’API personnalisé doit être associé à un serveur de ressources (même identifiant). Comme pour les autres types d’octroi, vous pouvez aussi transmettre l’ID client dans le Authorization Header à l’aide de HTTP Basic Auth.

client_secret · string · requis

Le Secret client de votre client d’API personnalisé. Comme pour les autres types d’octroi, vous pouvez aussi transmettre le Secret client dans le Authorization Header à l’aide de HTTP Basic Auth. Consultez les options de remplacement dans la documentation de référence de l’Auth0 Authentication API. Notez que vous ne pouvez pas définir token_endpoint_auth_method à none pour l’échange de jetons OBO.

audience · string · requis

L’identifiant unique de l’API en aval à laquelle vous voulez accéder. Il s’agit de l’identifiant du service en aval qui reçoit et valide le nouveau jeton.

scope · string

(Facultatif) Liste de permissions précises, séparées par des espaces, demandées pour l’appel en aval. Si rien n’est précisé, tous les scopes accordés à l’utilisateur pour l’audience cible seront inclus selon les politiques RBAC.

​

Réponse

Statut	Description
200	Réponse réussie. Renvoie un jeton d’accès pour l’API en aval, tout en conservant la même identité d’utilisateur.
400	Requête incorrecte. Peut se produire si la profondeur de la chaîne de délégation dépasse la limite maximale autorisée de 4 niveaux imbriqués, ou si des paramètres obligatoires sont manquants.
401	Non autorisé. Le jeton de sujet est invalide ou expiré, ou les identifiants de l’application sont incorrects.
403	Interdit. L’application n’a pas la permission d’effectuer l’échange de jeton, ou l’utilisateur ne dispose pas des scopes demandés pour l’audience cible.

200 Réponse

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

​

Champs de réponse

access_token · string

Le nouveau jeton d’accès Auth0 destiné à l’API en aval et limité aux scopes correspondants. Ce JSON Web Token (JWT) contient le même sub (identité de l’utilisateur) que le jeton de sujet, avec aud défini sur l’audience demandée de l’API en aval. La revendication act permet de suivre la chaîne de délégation.

issued_token_type · string

Confirme le format du jeton renvoyé. Cela correspond au requested_token_type de votre demande.

Valeur : urn:ietf:params:oauth:token-type:access_token

token_type · string

Spécifie le schéma d’authentification à utiliser dans l’Authorization Header. Pour OBO, il s’agit de Bearer, sauf si vous utilisez DPoP, auquel cas DPoP sera utilisé.

expires_in · number

La durée de validité du jeton, en secondes.

scope · string

(Facultatif) Inclus uniquement si les scopes accordés diffèrent des scopes demandés. Liste des scopes réellement accordés, délimitée par des espaces.