Obtenir un jeton

Le On-Behalf-Of (OBO) Token Exchange permet à un service intermédiaire d’échanger un jeton utilisateur entrant contre un nouveau jeton limité au service en aval.

POST /oauth/token

Le On-Behalf-Of (OBO) Token Exchange (RFC 8693) permet aux services intermédiaires d’échanger un jeton utilisateur limité en portée 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é spécifiquement 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 suivie dans la claim act (actor), chaque niveau représentant un service dans la chaîne d’appels. Pour en savoir plus, consultez la documentation sur le On-Behalf-Of Token Exchange.

​

Remarques

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

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

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

• Les échanges de jeton 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 consigne l’ensemble de la chaîne de délégation.

• La chaîne de délégation est limitée à cinq niveaux imbriqués. Comme l’échange ajoute le client actuel comme niveau supplémentaire, l’échange de jeton OBO échoue si le jeton sujet comporte déjà quatre niveaux act imbriqués.

• Mettez en cache les jetons d’accès pendant 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; les échanges de jeton 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 Demonstrating Proof-of-Possession.

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 Suspicious IP Throttling fonctionne dans des scénarios côté serveur.

​

Corps de la requête

grant_type · string · requis

Indique le flux que vous utilisez. Pour On-Behalf-Of Token Exchange, utilisez urn:ietf:params:oauth:grant-type:token-exchange.

subject_token_type · string · requis

Le type du jeton sujet. Pour On-Behalf-Of Token Exchange, 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 dont le service intermédiaire dispose actuellement.

requested_token_type · string · requis

Indique le type de jeton que vous souhaitez recevoir en retour. Pour On-Behalf-Of Token Exchange, utilisez urn:ietf:params:oauth:token-type:access_token.

client_id · string · requis

Le Client ID de votre client d’API personnalisée. Le client d’API personnalisée doit être associé à un serveur de ressources (même identifiant). Comme pour les autres types de grant, vous pouvez aussi transmettre le Client ID dans l’en-tête Authorization au moyen de l’authentification Basic HTTP.

client_secret · string · requis

Le Client Secret de votre client d’API personnalisée. Comme pour les autres types de grant, vous pouvez aussi transmettre le Client Secret dans l’en-tête Authorization au moyen de l’authentification Basic HTTP. Consultez les autres options dans la documentation de référence de l’API d’authentification Auth0. Notez que vous ne pouvez pas définir token_endpoint_auth_method sur 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 la requête en aval. S’il n’est pas 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. Retourne un jeton d’accès pour l’API en aval tout en conservant la même identité utilisateur.
400	Requête incorrecte. Peut se produire si le jeton sujet contient déjà quatre niveaux act imbriqués, ce qui représente le maximum que cet échange peut étendre, ou si des paramètres obligatoires sont manquants.
401	Non autorisé. Le jeton sujet est invalide ou expiré, ou les identifiants du client sont incorrects.
403	Interdit. Le client n’est pas autorisé à effectuer l’échange de jetons, ou l’utilisateur ne possède pas les scope 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"
}

Lorsqu’un client lié à un agent effectue l’échange, le claim act décodé du jeton d’accès retourné place l’agent comme acteur le plus externe et préserve la chaîne de délégation antérieure du jeton sujet sous la forme d’un act interne imbriqué :

{
  "act": {
    "sub": "agt_72jbvv7LfRKYp59gtRLtkn",
    "sub_profile": "ai_agent",
    "client_id": "K1AUPhZq8mRi0Q0pjhkfu1D7y6KjDQja",
    "iss": "https://tenant.auth0.com/",
    "act": {
      "sub": "mcp_server_client_id",
      "client_id": "mcp_server_client_id",
      "sub_profile": "service ai_agent",
      "iss": "https://tenant.auth0.com/"
    }
  }
}

​

Champs de réponse

access_token · string

Le nouveau jeton d’accès Auth0, limité à l’API en aval. Ce JSON Web Token (JWT) contient le même sub (identité de l’utilisateur) que le jeton sujet, et aud correspond à l’audience de l’API en aval demandée. La claim act assure le suivi de la chaîne de délégation.

Lorsqu’un client lié à un agent effectue l’échange et que les claims de sujet de l’agent sont activées pour l’API en aval, l’agent est l’acteur le plus externe de la claim act, et la chaîne de délégation précédente du jeton sujet est conservée dans la claim act interne imbriquée. Pour en savoir plus, consultez la claim act.

issued_token_type · string

Confirme le format du jeton renvoyé. Cette valeur correspond à requested_token_type dans votre requête.

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

token_type · string

Précise le schéma d’authentification à utiliser dans l’en-tête Authorization. Pour OBO, il s’agit de Bearer, sauf si vous utilisez DPoP, auquel cas DPoP sera utilisé.

expires_in · number

La durée de vie 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.