2. Introspection Endpoint (Point de terminaison d'introspection)

Le point de terminaison d'introspection est un point de terminaison OAuth 2.0 qui prend un paramètre représentant un jeton OAuth 2.0 et renvoie un document JSON [RFC7159] représentant les méta-informations entourant le jeton, y compris si ce jeton est actuellement actif. La définition d'un jeton actif dépend du serveur d'autorisation, mais il s'agit généralement d'un jeton qui a été émis par le serveur d'autorisation, qui n'est pas expiré, qui n'a pas été révoqué et qui est valide pour être utilisé par la ressource protégée effectuant l'appel d'introspection.

Le point de terminaison d'introspection DOIT être protégé par un mécanisme de sécurité de la couche transport tel que décrit dans la section 4. Les moyens par lesquels la ressource protégée découvre l'emplacement du point de terminaison d'introspection ne relèvent pas du domaine de cette spécification.

2.1. Introspection Request (Requête d'introspection)

La ressource protégée appelle le point de terminaison d'introspection en utilisant une requête HTTP POST [RFC7231] avec les paramètres envoyés sous forme de données "application/x-www-form-urlencoded" telles que définies dans [W3C.REC-html5-20141028]. La ressource protégée envoie un paramètre représentant le jeton ainsi que des paramètres optionnels représentant un contexte supplémentaire connu de la ressource protégée pour aider le serveur d'autorisation dans sa réponse.

token : REQUIS. La valeur de chaîne du jeton. Pour les jetons d'accès, il s'agit de la valeur "access_token" renvoyée par le point de terminaison de jeton défini dans OAuth 2.0 [RFC6749], Section 5.1. Pour les jetons de rafraîchissement, il s'agit de la valeur "refresh_token" renvoyée par le point de terminaison de jeton tel que défini dans OAuth 2.0 [RFC6749], Section 5.1. Les autres types de jetons ne relèvent pas du domaine de cette spécification.

token_type_hint : OPTIONNEL. Indication sur le type de jeton soumis à l'introspection. La ressource protégée PEUT passer ce paramètre pour aider le serveur d'autorisation à optimiser la recherche de jeton. Si le serveur ne parvient pas à localiser le jeton à l'aide de l'indication donnée, il DOIT étendre sa recherche à tous les types de jetons pris en charge. Un serveur d'autorisation PEUT ignorer ce paramètre, en particulier s'il est capable de détecter le type de jeton automatiquement. Les valeurs de ce champ sont définies dans le registre "OAuth Token Type Hints" défini dans OAuth Token Revocation [RFC7009].

Le point de terminaison d'introspection PEUT accepter d'autres paramètres OPTIONNELS pour fournir un contexte supplémentaire à la requête. Par exemple, un serveur d'autorisation peut souhaiter connaître l'adresse IP du client accédant à la ressource protégée pour déterminer si le client correct est susceptible de présenter le jeton. La définition de ce paramètre ou de tout autre paramètre ne relève pas du domaine de cette spécification et doit être définie par la documentation du service ou des extensions à cette spécification. Si le serveur d'autorisation ne peut pas déterminer l'état du jeton sans informations supplémentaires, il DEVRAIT renvoyer une réponse d'introspection indiquant que le jeton n'est pas actif comme décrit dans la Section 2.2.

Pour empêcher les attaques par balayage de jetons, le point de terminaison DOIT également exiger une certaine forme d'autorisation pour accéder à ce point de terminaison, telle que l'authentification du client décrite dans OAuth 2.0 [RFC6749] ou un jeton d'accès OAuth 2.0 distinct tel que le jeton porteur décrit dans OAuth 2.0 Bearer Token Usage [RFC6750]. Les méthodes de gestion et de validation de ces informations d'authentification ne relèvent pas du domaine de cette spécification.

Par exemple, ce qui suit montre une ressource protégée appelant le point de terminaison d'introspection de jeton pour se renseigner sur un jeton porteur OAuth 2.0. La ressource protégée utilise un jeton porteur OAuth 2.0 distinct pour autoriser cet appel.

Ce qui suit est un exemple de requête non normatif :

POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483

token=2YotnFZFEjr1zCsicMWpAA

Dans cet exemple, la ressource protégée utilise un identifiant client et un secret client pour s'authentifier auprès du point de terminaison d'introspection. La ressource protégée envoie également une indication de type de jeton indiquant qu'elle se renseigne sur un jeton d'accès.

Ce qui suit est un exemple de requête non normatif :

POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=mF_9.B5f-4.1JqM&token_type_hint=access_token

2.2. Introspection Response (Réponse d'introspection)

Le serveur répond avec un objet JSON [RFC7159] au format "application/json" avec les membres de premier niveau suivants.

active : REQUIS. Indicateur booléen indiquant si le jeton présenté est actuellement actif ou non. Les spécificités de l'état "actif" d'un jeton varieront en fonction de l'implémentation du serveur d'autorisation et des informations qu'il conserve sur ses jetons, mais une valeur "true" renvoyée pour la propriété "active" indiquera généralement qu'un jeton donné a été émis par ce serveur d'autorisation, n'a pas été révoqué par le propriétaire de la ressource et se trouve dans sa fenêtre de validité donnée (par exemple, après son heure d'émission et avant son heure d'expiration). Voir la Section 4 pour des informations sur la mise en œuvre de tels contrôles.

scope : OPTIONNEL. Une chaîne JSON contenant une liste séparée par des espaces de portées associées à ce jeton, au format décrit dans la Section 3.3 d'OAuth 2.0 [RFC6749].

client_id : OPTIONNEL. Identifiant client du client OAuth 2.0 qui a demandé ce jeton.

username : OPTIONNEL. Identifiant lisible par l'homme pour le propriétaire de la ressource qui a autorisé ce jeton.

token_type : OPTIONNEL. Type du jeton tel que défini dans la Section 5.1 d'OAuth 2.0 [RFC6749].

exp : OPTIONNEL. Horodatage entier, mesuré en nombre de secondes depuis le 1er janvier 1970 UTC, indiquant quand ce jeton expirera, tel que défini dans JWT [RFC7519].

iat : OPTIONNEL. Horodatage entier, mesuré en nombre de secondes depuis le 1er janvier 1970 UTC, indiquant quand ce jeton a été émis à l'origine, tel que défini dans JWT [RFC7519].

nbf : OPTIONNEL. Horodatage entier, mesuré en nombre de secondes depuis le 1er janvier 1970 UTC, indiquant quand ce jeton ne doit pas être utilisé avant, tel que défini dans JWT [RFC7519].

sub : OPTIONNEL. Sujet du jeton, tel que défini dans JWT [RFC7519]. Généralement un identifiant lisible par machine du propriétaire de la ressource qui a autorisé ce jeton.

aud : OPTIONNEL. Identifiant de chaîne spécifique au service ou liste d'identifiants de chaîne représentant l'audience prévue pour ce jeton, tel que défini dans JWT [RFC7519].

iss : OPTIONNEL. Chaîne représentant l'émetteur de ce jeton, tel que défini dans JWT [RFC7519].

jti : OPTIONNEL. Identifiant de chaîne pour le jeton, tel que défini dans JWT [RFC7519].

Des implémentations spécifiques PEUVENT étendre cette structure avec leurs propres noms de réponse spécifiques au service en tant que membres de premier niveau de cet objet JSON. Les noms de réponse destinés à être utilisés entre domaines DOIVENT être enregistrés dans le registre "OAuth Token Introspection Response" défini dans la Section 3.1.

Le serveur d'autorisation PEUT répondre différemment aux différentes ressources protégées effectuant la même requête. Par exemple, un serveur d'autorisation PEUT limiter les portées d'un jeton donné qui sont renvoyées pour chaque ressource protégée afin d'empêcher une ressource protégée d'en apprendre plus sur le réseau plus large qu'il n'est nécessaire pour son fonctionnement.

La réponse PEUT être mise en cache par la ressource protégée pour améliorer les performances et réduire la charge sur le point de terminaison d'introspection, mais au prix de la vivacité des informations utilisées par la ressource protégée pour prendre des décisions d'autorisation. Voir la Section 4 pour plus d'informations concernant le compromis lorsque la réponse est mise en cache.

Par exemple, la réponse suivante contient un ensemble d'informations sur un jeton actif :

Ce qui suit est un exemple de réponse non normatif :

HTTP/1.1 200 OK
Content-Type: application/json

{
 "active": true,
 "client_id": "l238j323ds-23ij4",
 "username": "jdoe",
 "scope": "read write dolphin",
 "sub": "Z5O3upPC88QrAjx00dis",
 "aud": "https://protected.example.net/resource",
 "iss": "https://server.example.com/",
 "exp": 1419356238,
 "iat": 1419350238,
 "extension_field": "twenty-seven"
}

Si l'appel d'introspection est correctement autorisé mais que le jeton n'est pas actif, n'existe pas sur ce serveur ou si la ressource protégée n'est pas autorisée à introspecter ce jeton particulier, alors le serveur d'autorisation DOIT renvoyer une réponse d'introspection avec le champ "active" défini sur "false". Notez que pour éviter de divulguer trop d'état du serveur d'autorisation à un tiers, le serveur d'autorisation NE DEVRAIT PAS inclure d'informations supplémentaires sur un jeton inactif, y compris la raison pour laquelle le jeton est inactif.

Ce qui suit est un exemple de réponse non normatif pour un jeton qui a été révoqué ou est autrement invalide :

HTTP/1.1 200 OK
Content-Type: application/json

{
 "active": false
}

2.3. Error Response (Réponse d'erreur)

Si la ressource protégée utilise des informations d'identification de client OAuth 2.0 pour s'authentifier auprès du point de terminaison d'introspection et que ses informations d'identification ne sont pas valides, le serveur d'autorisation répond par un code HTTP 401 (Unauthorized) comme décrit dans la Section 5.2 d'OAuth 2.0 [RFC6749].

Si la ressource protégée utilise un jeton porteur OAuth 2.0 pour autoriser son appel au point de terminaison d'introspection et que le jeton utilisé pour l'autorisation ne contient pas de privilèges suffisants ou est autrement invalide pour cette requête, le serveur d'autorisation répond par un code HTTP 401 comme décrit dans la Section 3 d'OAuth 2.0 Bearer Token Usage [RFC6750].

Notez qu'une requête correctement formée et autorisée pour un jeton inactif ou autrement invalide (ou un jeton que la ressource protégée n'est pas autorisée à connaître) n'est pas considérée comme une réponse d'erreur par cette spécification. Dans ces cas, le serveur d'autorisation DOIT plutôt répondre par une réponse d'introspection avec le champ "active" défini sur "false" comme décrit dans la Section 2.2.