Skip to main content
L’échange de jetons On-Behalf-Of (OBO) (RFC 8693) permet aux services intermédiaires de préserver l’identité et les permissions de l’utilisateur lorsqu’ils appellent des API en aval. Lorsqu’une application doit appeler une API en aval, elle peut utiliser :
  • Client Credentials Flow : l’application agit pour son propre compte et s’authentifie elle-même. La requête peut avoir été initiée par un utilisateur, mais ce contexte sera perdu. Le service en aval ne connaît alors que l’identité de l’application appelante.
  • On-Behalf-Of (OBO) Token Exchange : l’application reçoit un jeton limité aux portées de l’utilisateur et peut l’échanger contre un nouveau jeton pour appeler des services en aval. Cela préserve l’identité et le contexte de l’utilisateur final d’origine tout au long de la chaîne d’appel.
Par exemple, si un utilisateur déclenche un appel vers le Service A, qui appelle ensuite le Service B, l’échange de jetons OBO permet au Service A d’échanger le jeton d’accès de l’utilisateur contre un nouveau jeton qui :
  • conserve l’identité et les permissions de l’utilisateur d’origine
  • est limité spécifiquement au Service B
  • permet au Service B de prendre des décisions d’autorisation en fonction de l’utilisateur final
Les échanges de jetons OBO déclenchent le trigger d’Action post-login, où : Comme dans un flux de connexion standard, les portées renvoyées pour les appels d’API en aval sont basées sur les politiques de contrôle d’accès basé sur les rôles (RBAC) de l’utilisateur.
Lorsque vous achetez le module complémentaire Auth0 for AI Agents, vous pouvez utiliser la limite de débit maximale de l’Authentication API de votre niveau d’abonnement pour les échanges de jetons OBO. Par exemple, si vous utilisez Private Cloud 100 RPS, vous pouvez dépasser la limite de débit de 30 RPS des échanges de jetons OBO et tirer pleinement parti de la capacité de 100 RPS pour vos requêtes d’échange de jetons OBO. La limite de l’Authentication API est partagée et agit comme plafond global pour toutes les requêtes de l’Authentication API, y compris les connexions, les actualisations de jetons et les échanges de jetons combinés. Communiquez avec votre gestionnaire de compte technique pour en savoir plus.

Cas d’utilisation

Parmi les cas d’utilisation courants de l’échange de jeton OBO, on retrouve :
  • Les serveurs MCP qui doivent appeler des API de première partie au nom de l’utilisateur
  • Les microservices qui doivent appeler des services en aval au nom de l’utilisateur
Pour permettre à vos applications d’appeler des API tierces au nom de l’utilisateur, utilisez Token Vault.

Fonctionnement

L’échange de jeton OBO permet aux services intermédiaires d’échanger un jeton utilisateur reçu contre un nouveau jeton limité à un service en aval. Ce nouveau jeton conserve l’identité de l’utilisateur d’origine tout en assurant le suivi de la chaîne des services impliqués dans la charge utile du JSON Web Token (JWT).

Exemple : appels du serveur MCP à une API de première partie

Un utilisateur s’authentifie auprès d’Auth0 dans une application cliente, qui appelle ensuite un serveur MCP; celui-ci doit ensuite appeler une API de première partie.

Étape 1 : Authentification de l’utilisateur

Lorsque l’utilisateur se connecte, Auth0 émet un jeton d’accès limité au serveur MCP, avec les claims suivantes dans la charge utile du JWT :

Étape 2 : échange OBO

À l’aide de l’échange de jeton OBO, le serveur MCP présente le jeton de l’utilisateur à Auth0 et demande un jeton d’accès dont la portée est limitée à l’API de première partie. Auth0 émet un nouveau jeton d’accès pour l’API, avec les claims suivants :

La claim act

La claim act (acteur) retrace l’ensemble de la chaîne de délégation. Chaque niveau act représente un service dans la chaîne d’appels, et le act.sub le plus externe identifie l’acteur actuel qui a effectué l’échange de jeton. Dans notre exemple :
  • act.sub le plus externe : mcp_server_client_id (le serveur MCP qui vient tout juste d’échanger le jeton)
  • act.sub imbriqué : spa_client_id (l’application cliente d’origine)
La claim azp doit correspondre à la valeur du act.sub le plus externe, afin d’identifier le service qui a effectué l’échange de jeton le plus récent. Si l’API de première partie appelle un autre service en aval (https://calendar-api.acme.com), la chaîne de délégation s’étendrait :
La chaîne de délégation ne peut pas comporter plus de cinq niveaux imbriqués. Comme l’échange ajoute le client actuel comme niveau supplémentaire, l’échange de jeton OBO échouera si le jeton du sujet comporte déjà quatre niveaux act imbriqués.
Mettez en cache les jetons d’accès pendant 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 tant qu’ils n’ont pas expiré; des échanges de jetons à répétition gaspillent des ressources, augmentent la latence et peuvent vous faire atteindre les limites de requêtes.

Utilisateur > serveur MCP > flux API

Le diagramme suivant illustre un flux de bout en bout d’échange de jeton OBO dans lequel un serveur MCP appelle une API de première partie pour le compte de l’utilisateur :
  1. Authentification de l’utilisateur : L’utilisateur s’authentifie auprès de l’application cliente. L’Auth0 Authorization Server émet le jeton A, limité au MCP Server.
  2. Requête initiale : L’application cliente appelle le MCP Server en transmettant le jeton A dans l’en-tête Authorization: Bearer.
  3. Validation et échange de jetons : Le MCP Server reçoit le jeton A, le valide et le transmet au point de terminaison /oauth/token de l’Auth0 Authorization Server. Au moyen de l’échange de jeton OBO, le MCP Server présente le jeton A comme subject_token et demande un nouveau jeton pour l’API de première partie.
  4. Émission du jeton : L’Auth0 Authorization Server émet le jeton B. Le jeton B a le même sub (ID utilisateur) que le jeton A, mais le aud (audience) correspond maintenant à l’API de première partie.
  5. Requête en aval : Le MCP Server appelle l’API de première partie au moyen du jeton B. L’API valide le jeton B et constate que la requête est bien effectuée « au nom de » l’utilisateur d’origine.

Utilisateur > API1 > API2 > API3

Le schéma suivant illustre le fonctionnement de bout en bout d’une chaîne de microservices qui effectuent des appels aux services en aval au nom de l’utilisateur :
  1. Authentification de l’utilisateur : L’utilisateur s’authentifie avec succès auprès d’une application cliente. L’Auth0 Authorization Server émet le jeton A, dont la portée est limitée à API1.
  2. Requête initiale : L’application cliente envoie une requête à API1 en transmettant le jeton A dans l’en-tête Authorization: Bearer.
  3. API1 délègue à API2 : API1 reçoit le jeton A, le valide, puis le transmet au point de terminaison /oauth/token de l’Auth0 Authorization Server. En utilisant l’échange de jeton OBO, API1 présente le jeton A comme subject_token et demande un nouveau jeton pour API2.
  4. Émission de jeton : L’Auth0 Authorization Server accorde un nouveau jeton d’accès, le jeton B, à API1. Le jeton B a le même sub (ID utilisateur) que le jeton A, mais le aud (audience) est maintenant API2.
  5. Requête en aval : API1 envoie une requête à API2 à l’aide du jeton B.
  6. API2 délègue à API3 : API2 reçoit le jeton B, le valide, puis le transmet au point de terminaison /oauth/token de l’Auth0 Authorization Server. En utilisant l’échange de jeton OBO, API2 présente le jeton B comme subject_token et demande un nouveau jeton pour API3.
  7. Émission de jeton : L’Auth0 Authorization Server accorde un nouveau jeton d’accès, le jeton C, à API2. Le jeton C a le même sub (ID utilisateur) que les jetons A et B, mais le aud (audience) est maintenant API3.
  8. Requête en aval : API2 envoie une requête à API3 à l’aide du jeton C. API3 valide le jeton C et constate que la requête est bien effectuée « au nom de » l’utilisateur d’origine.

Prérequis

Seuls les clients d’API personnalisée associés à un serveur de ressources peuvent utiliser l’échange de jetons OBO. Un client d’API personnalisée est lié à un serveur de ressources lorsqu’ils ont le même identifiant. Les clients d’API personnalisée doivent respecter les exigences suivantes :
  • Définissez app_type sur resource_server.
  • Définissez resource_server_identifier sur un identifiant de 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.
Comme les clients d’API personnalisée sont des clients de première partie, assurez-vous de ne pas demander le consentement de l’utilisateur pour les API auxquelles votre client de première partie doit accéder.

Créer un client d’API personnalisé

Vous pouvez créer un client d’API personnalisé à l’aide de l’Auth0 Dashboard ou de la Management API.
Pour créer un client d’API personnalisé dans l’Auth0 Dashboard :
  1. Accédez à Applications > APIs et sélectionnez votre API backend.
My Test OBO API
  1. Sélectionnez Add Application et saisissez un nom d’application.
  2. Sélectionnez Add.
Une fois l’application créée, consultez-la en sélectionnant Configure Application, puis faites défiler jusqu’à Application Properties. Le champ Application Type est Custom API Client.
My Test OBO API

Créer un client grant

Vous devez créer un client grant avec accès délégué par l’utilisateur entre le client d’API personnalisée et l’API en aval afin d’autoriser l’accès.
  1. Accédez à Applications > Applications et sélectionnez votre client d’API personnalisée.
  2. Sous API Access, repérez votre serveur de ressources (c.-à-d. https://my-api.example.com) et sélectionnez Edit.
  3. Sous User-Delegated Access, sélectionnez Grant Access, puis sélectionnez les permissions à accorder, ou Always grant all permissions.
  4. Sélectionnez Save.

Configurer l’échange de jetons OBO

Découvrez comment configurer votre client d’API personnalisé pour utiliser le type d’octroi d’échange de jetons OBO.
  1. Accédez à Applications > Applications et sélectionnez votre client d’API personnalisé.
  2. Sous Token Exchange, activez On-Behalf-Of Token Exchange.
  3. Sélectionnez Save.
Mon API OBO de test

Effectuer un échange de jetons OBO

Pour effectuer l’échange de jetons OBO, vous pouvez utiliser auth0-api-js, auth0_api_python ou l’Authentication API.
Mettez les jetons d’accès en cache pour toute la durée de vie 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; des échanges de jetons répétés gaspillent des ressources, augmentent la latence et peuvent entraîner l’application de limites de débit.
Avant de commencer, assurez-vous d’avoir installé la bibliothèque auth0-api-js et ses dépendances.Commencez par initialiser ApiClient avec les identifiants de votre serveur MCP :
Ensuite, utilisez la méthode getTokenOnBehalfOf() pour procéder à l’échange de jetons :
getTokenOnBehalfOf() retourne un objet contenant :
  • accessToken : Le nouveau token pour votre API en aval
  • scope : Les scopes accordés
  • expiresIn : La durée d’expiration du token, en secondes

Token Binding

Lorsque des jetons sont liés à l’émetteur au moyen de DPoP ou de mTLS, seul le détenteur de la clé ou du certificat en question peut en prouver la possession et utiliser le jeton.Lors d’un échange OBO, le service intermédiaire détient le jeton.Auth0 ne peut pas vérifier cryptographiquement que le service intermédiaire détient la clé ou le certificat du détenteur initial; il ne vérifie donc pas de nouveau le Token Binding du jeton initial durant l’échange.Le service intermédiaire doit :
  • Vérifier le Token Binding
  • Lier les nouveaux jetons
  • Gérer le mécanisme de commutation entre DPoP et mTLS
La vérification du Token Binding relève du service intermédiaire. La liaison est une preuve cryptographique que le détenteur du jeton possède la clé ou le certificat du détenteur initial. Avant d’échanger un jeton lié, validez que le Token Binding du jeton initial a été vérifié :
  • DPoP : calculez l’empreinte JWK SHA-256 du jwk dans la preuve DPoP entrante (conformément à la RFC 7638) et vérifiez qu’elle correspond à la revendication cnf.jkt du jeton de sujet. Auth0 n’effectue pas cette vérification durant l’échange de jetons.
  • mTLS : calculez l’empreinte SHA-256, encodée en base64url, de l’encodage DER du certificat client et vérifiez qu’elle correspond à la revendication cnf.x5t#S256 du jeton de sujet.
Si la validation échoue, rejetez la requête sans tenter l’échange. Liaison du nouveau jeton : Auth0 liera le jeton d’accès nouvellement émis à l’émetteur lorsque le serveur de ressources en aval a la liaison à l’émetteur activée ou obligatoire et que le service intermédiaire présente une preuve DPoP ou un certificat mTLS valide au point de terminaison /oauth/token. Si aucune preuve DPoP ni aucun certificat mTLS n’est présenté, Auth0 émet un jeton porteur non lié, quel que soit l’état de liaison du jeton de sujet initial. Transitions entre les mécanismes de liaison et capacités incompatibles : Le service intermédiaire peut changer de mécanisme de liaison durant un échange OBO (par exemple, de DPoP à mTLS), à condition de posséder les identifiants nécessaires au nouveau mécanisme (par exemple, un certificat mTLS provisionné). Le jeton nouvellement émis reflète le nouveau type de liaison. Avant l’échange, vérifiez que l’API en aval prend en charge le mécanisme de liaison présenté. Auth0 ne valide pas la compatibilité des mécanismes; il émettra le jeton dans tous les cas. Si l’API en aval ne prend pas en charge le mécanisme présenté, elle rejettera le jeton à l’exécution. Si les mécanismes ne peuvent pas être conciliés, ne tentez pas l’échange; retournez plutôt une erreur à l’appelant. Nonces DPoP : Si le jeton de sujet initial a été émis pour un client public (comme une SPA ou une application mobile) à l’aide de DPoP avec un nonce émis par le serveur, le service intermédiaire pourrait ne pas disposer d’un nonce valide pour établir une nouvelle liaison au point de terminaison /oauth/token. Dans ce cas, Auth0 retourne une erreur use_dpop_nonce accompagnée d’un nouveau nonce dans l’en-tête de réponse DPoP-Nonce. Réessayez la requête en utilisant ce nonce dans la nouvelle preuve DPoP.
Si le jeton de sujet initial était lié à l’émetteur, mais que le service intermédiaire ne présente pas de justificatifs de liaison (preuve DPoP ou certificat mTLS) au point de terminaison /oauth/token, Auth0 ne rejette pas la requête; il émet plutôt un jeton porteur non lié sans signaler d’erreur. L’API en aval l’acceptera sans preuve de possession, ce qui le rend réutilisable s’il est intercepté. Si le serveur de ressources en aval exige des jetons liés à l’émetteur, ne transmettez pas le jeton non lié. Rejetez-le et renvoyez une erreur à l’appelant.

Prise en charge d’Organizations

Lorsqu’un utilisateur s’authentifie via une organisation, le jeton d’accès comprend une claim org_id. L’échange de jeton OBO préserve ce contexte de l’organisation tout au long de la chaîne de délégation. Quand Auth0 reçoit une demande d’échange de jeton OBO avec un jeton d’accès associé à une organisation, il vérifie :
  • que org_id existe dans votre tenant
  • que l’utilisateur (identifié par sub) est membre de cette organisation
Si la validation échoue, Auth0 rejette la demande d’échange de jeton. Si elle réussit, Auth0 émet un nouveau jeton d’accès qui :
  • contient la même claim org_id que le jeton d’origine
  • applique les mêmes politiques RBAC propres à l’organisation
  • rend le contexte de l’organisation accessible dans le déclencheur post-login d’Actions via la propriété event.organization