2. Demande et réponse d'échange de jetons

2.1. Demande

Un client demande un jeton de sécurité en effectuant une demande de jeton auprès du point de terminaison de jeton du serveur d'autorisation en utilisant le mécanisme de type d'autorisation d'extension défini dans la section 4.5 de la [RFC6749].

L'authentification du client auprès du serveur d'autorisation est effectuée à l'aide des mécanismes normaux fournis par OAuth 2.0. La section 2.3.1 de la [RFC6749] définit l'authentification basée sur le mot de passe du client, cependant, l'authentification du client est extensible et d'autres mécanismes sont possibles. Par exemple, la [RFC7523] définit l'authentification du client à l'aide de jetons Web JSON (JWT) porteurs [JWT]. Les méthodes d'authentification du client prises en charge et le fait d'autoriser ou non des clients non authentifiés ou non identifiés sont des décisions de déploiement qui sont à la discrétion du serveur d'autorisation. Notez que l'omission de l'authentification du client permet à un jeton compromis d'être exploité via un STS en d'autres jetons par toute personne possédant le jeton compromis. Ainsi, l'authentification du client permet des vérifications d'autorisation supplémentaires par le STS quant aux entités autorisées à usurper l'identité ou à recevoir des délégations d'autres entités.

Le client effectue une demande d'échange de jeton au point de terminaison de jeton avec un type d'autorisation d'extension en utilisant la méthode HTTP "POST". Les paramètres suivants sont inclus dans le corps de l'entité de la requête HTTP en utilisant le format "application/x-www-form-urlencoded" avec un codage de caractères UTF-8 comme décrit à l'annexe B de la [RFC6749].

grant_type REQUIS (REQUIRED). La valeur urn:ietf:params:oauth:grant-type:token-exchange indique qu'un échange de jeton est en cours.

resource OPTIONNEL (OPTIONAL). Un URI qui indique le service ou la ressource cible où le client a l'intention d'utiliser le jeton de sécurité demandé. Cela permet au serveur d'autorisation d'appliquer une politique appropriée pour la cible, telle que la détermination du type et du contenu du jeton à émettre ou si et comment le jeton doit être chiffré. Dans de nombreux cas, un client n'aura pas connaissance de l'organisation logique des systèmes avec lesquels il interagit et ne connaîtra que l'URI du service où il a l'intention d'utiliser le jeton. Le paramètre resource permet au client d'indiquer au serveur d'autorisation où il a l'intention d'utiliser le jeton émis en fournissant l'emplacement, généralement sous forme d'URL https, dans la demande d'échange de jeton sous la même forme que celle qui sera utilisée pour accéder à cette ressource. Le serveur d'autorisation aura généralement la capacité de mapper une valeur d'URI de ressource à une politique appropriée. La valeur du paramètre resource DOIT être un URI absolu, tel que spécifié par la section 4.3 de la [RFC3986], qui PEUT inclure un composant de requête et NE DOIT PAS inclure de composant de fragment. Plusieurs paramètres resource peuvent être utilisés pour indiquer que le jeton émis est destiné à être utilisé pour les multiples ressources répertoriées. Voir [OAUTH-RESOURCE] pour plus de contexte et d'utilisations du paramètre resource.

audience OPTIONNEL (OPTIONAL). Le nom logique du service cible où le client a l'intention d'utiliser le jeton de sécurité demandé. Cela sert un objectif similaire au paramètre resource, mais avec le client fournissant un nom logique pour le service cible. L'interprétation du nom nécessite que la valeur soit quelque chose que le client et le serveur d'autorisation comprennent tous les deux. Un identifiant de client OAuth, un identifiant d'entité SAML [OASIS.saml-core-2.0-os] et un identifiant d'émetteur OpenID Connect [OpenID.Core] sont des exemples de choses qui pourraient être utilisées comme valeurs de paramètre audience. Cependant, les valeurs audience utilisées avec un serveur d'autorisation donné doivent être uniques au sein de ce serveur pour garantir qu'elles sont correctement interprétées comme le type de valeur prévu. Plusieurs paramètres audience peuvent être utilisés pour indiquer que le jeton émis est destiné à être utilisé auprès des multiples audiences répertoriées. Les paramètres audience et resource peuvent être utilisés ensemble pour indiquer plusieurs services cibles avec un mélange de noms logiques et d'URI de ressources.

scope OPTIONNEL (OPTIONAL). Une liste de chaînes sensibles à la casse délimitées par des espaces, telles que définies dans la section 3.3 de la [RFC6749], qui permettent au client de spécifier la portée souhaitée du jeton de sécurité demandé dans le contexte du service ou de la ressource où le jeton sera utilisé. Les valeurs et la sémantique associée de la portée sont spécifiques au service et devraient être décrites dans la documentation pertinente du service.

requested_token_type OPTIONNEL (OPTIONAL). Un identifiant, tel que décrit dans la section 3, pour le type du jeton de sécurité demandé. Si le type demandé n'est pas spécifié, le type de jeton émis est à la discrétion du serveur d'autorisation et peut être dicté par la connaissance des exigences du service ou de la ressource indiquée par le paramètre resource ou audience.

subject_token REQUIS (REQUIRED). Un jeton de sécurité qui représente l'identité de la partie au nom de laquelle la demande est faite. Généralement, le sujet de ce jeton sera le sujet du jeton de sécurité émis en réponse à la demande.

subject_token_type REQUIS (REQUIRED). Un identifiant, tel que décrit dans la section 3, qui indique le type du jeton de sécurité dans le paramètre subject_token.

actor_token OPTIONNEL (OPTIONAL). Un jeton de sécurité qui représente l'identité de la partie agissante. Généralement, ce sera la partie qui est autorisée à utiliser le jeton de sécurité demandé et à agir au nom du sujet.

actor_token_type Un identifiant, tel que décrit dans la section 3, qui indique le type du jeton de sécurité dans le paramètre actor_token. Ceci est REQUIS lorsque le paramètre actor_token est présent dans la demande, mais NE DOIT PAS être inclus autrement.

Lors du traitement de la demande, le serveur d'autorisation DOIT effectuer les procédures de validation appropriées pour le type de jeton indiqué et, si le jeton d'acteur est présent, effectuer également les procédures de validation appropriées pour son type de jeton indiqué. Les critères de validité et les détails de tout jeton particulier sortent du cadre de ce document et sont spécifiques au type de jeton respectif et à son contenu.

En l'absence d'une utilisation unique ou d'autres sémantiques spécifiques au type de jeton, l'acte d'effectuer un échange de jetons n'a aucun impact sur la validité du jeton sujet ou du jeton acteur. De plus, l'échange est un événement unique et ne crée pas de lien étroit entre les jetons d'entrée et de sortie, de sorte que (par exemple) bien que le délai d'expiration du jeton de sortie puisse être influencé par celui du jeton d'entrée, le renouvellement ou l'extension du jeton d'entrée ne devrait pas être reflété dans les propriétés du jeton de sortie. Il peut toujours être approprié ou souhaitable de propager les événements de révocation de jeton. Cependant, le faire n'est pas une propriété générale du protocole STS et serait spécifique à une implémentation, un type de jeton ou un déploiement particulier.

2.1.1. Relation entre ressource, audience et portée

Lors de la demande d'un jeton, le client peut indiquer le ou les services cibles souhaités où il a l'intention d'utiliser ce jeton au moyen des paramètres audience et resource et indiquer la portée souhaitée du jeton demandé à l'aide du paramètre scope. La sémantique d'une telle demande est que le client demande un jeton avec la portée demandée qui est utilisable sur tous les services cibles demandés. Effectivement, les droits d'accès demandés du jeton sont le produit cartésien de toutes les portées sur tous les services cibles.

Un serveur d'autorisation peut ne pas vouloir ou ne pas pouvoir satisfaire une demande de jeton, mais la probabilité d'une demande irréalisable est considérablement plus élevée lorsque des droits d'accès très larges sont sollicités. En tant que tel, en l'absence de connaissances spécifiques sur la relation des systèmes dans un déploiement, les clients devraient faire preuve de discrétion dans l'étendue de l'accès demandé, en particulier le nombre de services cibles. Un serveur d'autorisation peut utiliser le code d'erreur invalid_target, défini dans la section 2.2.2, pour informer un client qu'il a demandé l'accès à trop de services cibles simultanément.

2.2. Réponse

Le serveur d'autorisation répond à une demande d'échange de jeton avec une réponse OAuth 2.0 normale du point de terminaison de jeton, comme spécifié dans la section 5 de la [RFC6749]. Des détails et des explications supplémentaires sont fournis dans les sous-sections suivantes.

2.2.1. Réponse réussie

Si la demande est valide et répond à toutes les politiques et autres critères du serveur d'autorisation, une réponse de jeton réussie est construite en ajoutant les paramètres suivants au corps de l'entité de la réponse HTTP en utilisant le type de support "application/json", comme spécifié par [RFC8259], et un code d'état HTTP 200. Les paramètres sont sérialisés dans une structure JSON (JavaScript Object Notation) en ajoutant chaque paramètre au niveau supérieur. Les noms de paramètres et les valeurs de chaîne sont inclus sous forme de chaînes JSON. Les valeurs numériques sont incluses sous forme de nombres JSON. L'ordre des paramètres n'a pas d'importance et peut varier.

access_token REQUIS (REQUIRED). Le jeton de sécurité émis par le serveur d'autorisation en réponse à la demande d'échange de jeton. Le paramètre access_token de la section 5.1 de la [RFC6749] est utilisé ici pour transporter le jeton demandé, ce qui permet à ce protocole d'échange de jetons d'utiliser les constructions de demande et de réponse OAuth 2.0 existantes définies pour le point de terminaison de jeton. L'identifiant access_token est utilisé pour des raisons historiques et le jeton émis n'a pas besoin d'être un jeton d'accès OAuth.

issued_token_type REQUIS (REQUIRED). Un identifiant, tel que décrit dans la section 3, pour la représentation du jeton de sécurité émis.

token_type REQUIS (REQUIRED). Une valeur insensible à la casse spécifiant la méthode d'utilisation du jeton d'accès émis, comme spécifié dans la section 7.1 de la [RFC6749]. Il fournit au client des informations sur la manière d'utiliser le jeton d'accès pour accéder aux ressources protégées. Par exemple, une valeur de "Bearer", telle que spécifiée dans [RFC6750], indique que le jeton de sécurité émis est un jeton porteur et que le client peut simplement le présenter tel quel sans aucune preuve d'éligibilité supplémentaire au-delà du contenu du jeton lui-même. Notez que la signification de ce paramètre est différente de la signification du paramètre issued_token_type, qui déclare la représentation du jeton de sécurité émis ; le terme "type de jeton" est plus généralement utilisé pour signifier la représentation structurelle ou syntaxique du jeton de sécurité, comme c'est le cas dans tous les paramètres *_token_type de cette spécification. Si le jeton émis n'est pas un jeton d'accès ou utilisable comme un jeton d'accès, alors la valeur token_type "N_A" est utilisée pour indiquer qu'un identifiant token_type OAuth 2.0 n'est pas applicable dans ce contexte.

expires_in RECOMMANDÉ (RECOMMENDED). La durée de validité, en secondes, du jeton émis par le serveur d'autorisation. Souvent, le client n'aura pas l'envie ou la capacité d'inspecter le contenu du jeton, et ce paramètre fournit une indication cohérente et agnostique du type de jeton sur la durée pendant laquelle le jeton peut être considéré comme valide. Par exemple, la valeur 1800 indique que le jeton expirera dans trente minutes à partir du moment où la réponse a été générée.

scope OPTIONNEL si la portée du jeton de sécurité émis est identique à la portée demandée par le client ; sinon, il est REQUIS.

refresh_token OPTIONNEL (OPTIONAL). Un jeton de rafraîchissement ne sera généralement pas émis lorsque l'échange concerne une information d'identification temporaire (le subject_token) pour une information d'identification temporaire différente (le jeton émis) à utiliser dans un autre contexte. Un jeton de rafraîchissement peut être émis dans les cas où le client de l'échange de jetons a besoin de pouvoir accéder à une ressource même lorsque l'information d'identification d'origine n'est plus valide (par exemple, scénarios où l'utilisateur n'est pas présent ou hors ligne où il n'y a plus d'utilisateur entretenant une session active avec le client). Les profils ou déploiements de cette spécification devraient documenter clairement les conditions dans lesquelles un client doit s'attendre à un jeton de rafraîchissement en réponse aux demandes de type d'autorisation urn:ietf:params:oauth:grant-type:token-exchange.

2.2.2. Réponse d'erreur

Si la demande elle-même n'est pas valide ou si le subject_token ou actor_token sont invalides pour une raison quelconque, ou sont inacceptables en fonction de la politique, le serveur d'autorisation DOIT construire une réponse d'erreur, telle que spécifiée dans la section 5.2 de la [RFC6749]. La valeur du paramètre error DOIT être le code d'erreur invalid_request.

Si le serveur d'autorisation ne veut pas ou ne peut pas émettre de jeton pour tout service cible indiqué par les paramètres resource ou audience, le code d'erreur invalid_target DEVRAIT être utilisé dans la réponse d'erreur.

Le serveur d'autorisation PEUT inclure des informations supplémentaires concernant les raisons de l'erreur en utilisant error_description comme discuté dans la section 5.2 de la [RFC6749].

D'autres codes d'erreur peuvent également être utilisés, selon le cas.

2.3. Exemple d'échange de jetons

L'exemple suivant illustre un échange de jetons hypothétique dans lequel un serveur de ressources OAuth assume le rôle du client pendant l'échange. Il échange un jeton d'accès, qu'il a reçu dans une demande de ressource protégée, contre un nouveau jeton qu'il utilisera pour appeler un service backend (les sauts de ligne et l'indentation supplémentaires dans les exemples sont uniquement à des fins d'affichage).

La figure 1 montre le serveur de ressources recevant une demande de ressource protégée contenant un jeton d'accès OAuth dans l'en-tête Authorization, comme spécifié dans la section 2.1 de la [RFC6750].

GET /resource HTTP/1.1
Host: frontend.example.com
Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC

Figure 1 : Demande de ressource protégée

Dans la figure 2, le serveur de ressources assume le rôle de client pour l'échange de jetons, et le jeton d'accès de la demande de la figure 1 est envoyé au serveur d'autorisation à l'aide d'une demande telle que spécifiée dans la section 2.1. La valeur du paramètre subject_token contient le jeton d'accès, et la valeur du paramètre subject_token_type indique qu'il s'agit d'un jeton d'accès OAuth 2.0. Le serveur de ressources, agissant dans le rôle du client, utilise son identifiant et son secret pour s'authentifier auprès du serveur d'autorisation en utilisant le schéma d'authentification HTTP Basic. Le paramètre resource indique l'emplacement du service backend, <https://backend.example.com/api>, où le jeton émis sera utilisé.

POST /as/token.oauth2 HTTP/1.1
Host: as.example.com
Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=https%3A%2F%2Fbackend.example.com%2Fapi
&subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC
&subject_token_type=
 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token

Figure 2 : Demande d'échange de jetons

Le serveur d'autorisation valide les informations d'identification du client et le subject_token présenté dans la demande d'échange de jeton. À partir du paramètre resource, le serveur d'autorisation est en mesure de déterminer la politique appropriée à appliquer à la demande et émet un jeton adapté à une utilisation sur <https://backend.example.com>. Le paramètre access_token de la réponse illustrée à la figure 3 contient le nouveau jeton, qui est lui-même un jeton d'accès OAuth porteur valide pendant une minute. Le jeton se trouve être un JWT ; cependant, sa structure et son format sont opaques pour le client, de sorte que le issued_token_type indique seulement qu'il s'agit d'un jeton d'accès.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo
   dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV
   4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn
   N1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQedw6rx
   f59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIWvmDCM
   y5-kdXjwhw",
 "issued_token_type":
     "urn:ietf:params:oauth:token-type:access_token",
 "token_type":"Bearer",
 "expires_in":60
}

Figure 3 : Réponse d'échange de jetons

Le serveur de ressources peut alors utiliser le jeton d'accès nouvellement acquis pour effectuer une demande au serveur backend comme illustré à la figure 4.

GET /api HTTP/1.1
Host: backend.example.com
Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ
   iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2
   FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M
   zMsInN1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQe
   dw6rxf59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIW
   vmDCMy5-kdXjwhw

Figure 4 : Demande de ressource protégée backend

D'autres exemples peuvent être trouvés à l'annexe A.