2. Token Revocation (Révocation de jeton)

Les implémentations DOIVENT (MUST) prendre en charge la révocation des jetons de rafraîchissement et DEVRAIENT (SHOULD) prendre en charge la révocation des jetons d'accès (voir Note d'implémentation).

Le client demande la révocation d'un jeton particulier en effectuant une requête HTTP POST à l'URL de l'endpoint de révocation de jeton. Cette URL DOIT (MUST) être conforme aux règles données dans [RFC6749], Section 3.1. Les clients DOIVENT (MUST) vérifier que l'URL est une URL HTTPS.

Les moyens d'obtenir l'emplacement de l'endpoint de révocation sont hors du cadre de cette spécification. Par exemple, le développeur client peut consulter la documentation du serveur ou une découverte automatique peut être utilisée. Comme cet endpoint gère des identifiants de sécurité, l'emplacement de l'endpoint doit être obtenu auprès d'une source digne de confiance.

Étant donné que les demandes adressées à l'endpoint de révocation de jeton entraînent la transmission d'identifiants en texte clair dans la requête HTTP, les URL des endpoints de révocation de jeton DOIVENT (MUST) être des URL HTTPS. Le serveur d'autorisation DOIT (MUST) utiliser Transport Layer Security (Sécurité de la couche de transport, TLS) [RFC5246] dans une version conforme à [RFC6749], Section 1.6. Les implémentations PEUVENT (MAY) également prendre en charge des mécanismes de sécurité de la couche de transport supplémentaires qui répondent à leurs exigences de sécurité.

Si l'hôte de l'endpoint de révocation de jeton peut également être atteint via HTTP, alors le serveur DEVRAIT (SHOULD) également offrir un service de révocation à l'URI HTTP correspondant, mais il NE DOIT PAS (MUST NOT) publier cette URI en tant qu'endpoint de révocation de jeton. Cela garantit que les jetons envoyés accidentellement via HTTP seront révoqués.

2.1. Revocation Request (Demande de révocation)

Le client construit la requête en incluant les paramètres suivants en utilisant le format "application/x-www-form-urlencoded" dans le corps de l'entité de la requête HTTP :

token : REQUIRED (REQUIS). Le jeton que le client souhaite faire révoquer.

token_type_hint : OPTIONAL (OPTIONNEL). Un indice sur le type de jeton soumis pour révocation. Les clients PEUVENT (MAY) passer ce paramètre afin d'aider le serveur d'autorisation à optimiser la recherche de jeton. Si le serveur ne parvient pas à localiser le jeton à l'aide de l'indice donné, il DOIT (MUST) étendre sa recherche à tous ses types de jetons pris en charge. Un serveur d'autorisation PEUT (MAY) ignorer ce paramètre, en particulier s'il est capable de détecter le type de jeton automatiquement. Cette spécification définit deux valeurs de ce type :

access_token: Un jeton d'accès tel que défini dans [RFC6749], Section 1.4
refresh_token: Un jeton de rafraîchissement tel que défini dans [RFC6749], Section 1.5

Les implémentations, profils et extensions spécifiques de cette spécification PEUVENT (MAY) définir d'autres valeurs pour ce paramètre en utilisant le registre défini à la Section 4.1.2.

Le client inclut également ses identifiants d'authentification comme décrit dans la Section 2.3 de [RFC6749].

Par exemple, un client peut demander la révocation d'un jeton de rafraîchissement avec la requête suivante :

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

token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token

Le serveur d'autorisation valide d'abord les identifiants du client (dans le cas d'un client confidentiel), puis vérifie si le jeton a été délivré au client effectuant la demande de révocation. Si cette validation échoue, la demande est refusée et le client est informé de l'erreur par le serveur d'autorisation comme décrit ci-dessous.

À l'étape suivante, le serveur d'autorisation invalide le jeton. L'invalidation a lieu immédiatement et le jeton ne peut plus être utilisé après la révocation. En pratique, il pourrait y avoir un délai de propagation, par exemple, dans lequel certains serveurs sont au courant de l'invalidation tandis que d'autres ne le sont pas. Les implémentations devraient minimiser cette fenêtre, et les clients ne doivent pas tenter d'utiliser le jeton après réception d'une réponse HTTP 200 du serveur.

Selon la politique de révocation du serveur d'autorisation, la révocation d'un jeton particulier peut entraîner la révocation des jetons associés et de l'octroi d'autorisation sous-jacent. Si le jeton particulier est un jeton de rafraîchissement et que le serveur d'autorisation prend en charge la révocation des jetons d'accès, alors le serveur d'autorisation DEVRAIT (SHOULD) également invalider tous les jetons d'accès basés sur le même octroi d'autorisation (voir Note d'implémentation). Si le jeton passé à la demande est un jeton d'accès, le serveur PEUT (MAY) également révoquer le jeton de rafraîchissement respectif.

Note : Un client conforme à [RFC6749] doit être prêt à gérer une invalidation de jeton inattendue à tout moment. Indépendamment du mécanisme de révocation spécifié dans ce document, les propriétaires de ressources peuvent révoquer des octrois d'autorisation, ou le serveur d'autorisation peut invalider des jetons afin d'atténuer les menaces de sécurité. Ainsi, avoir des politiques de serveur différentes concernant la révocation en cascade des jetons ne devrait pas poser de problèmes d'interopérabilité.

2.2. Revocation Response (Réponse de révocation)

Le serveur d'autorisation répond avec le code d'état HTTP 200 si le jeton a été révoqué avec succès ou si le client a soumis un jeton invalide.

Note : les jetons invalides ne provoquent pas de réponse d'erreur car le client ne peut pas gérer une telle erreur de manière raisonnable. De plus, le but de la demande de révocation, invalider le jeton particulier, est déjà atteint.

Le contenu du corps de la réponse est ignoré par le client car toutes les informations nécessaires sont véhiculées dans le code de réponse.

Une valeur d'indice de type de jeton invalide est ignorée par le serveur d'autorisation et n'influence pas la réponse de révocation.

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

La présentation de l'erreur est conforme à la définition de la Section 5.2 de [RFC6749]. Le code d'erreur supplémentaire suivant est défini pour l'endpoint de révocation de jeton :

unsupported_token_type : Le serveur d'autorisation ne prend pas en charge la révocation du type de jeton présenté. C'est-à-dire que le client a essayé de révoquer un jeton d'accès sur un serveur ne prenant pas en charge cette fonctionnalité.

Si le serveur répond avec le code d'état HTTP 503, le client doit supposer que le jeton existe toujours et peut réessayer après un délai raisonnable. Le serveur peut inclure un en-tête "Retry-After" dans la réponse pour indiquer combien de temps le service devrait être indisponible pour le client demandeur.

2.3. Cross-Origin Support (Support Cross-Origin)

L'endpoint de révocation PEUT (MAY) prendre en charge le Cross-Origin Resource Sharing (Partage de ressources cross-origin, CORS) [W3C.WD-cors-20120403] s'il est destiné à être utilisé en combinaison avec des applications basées sur un user-agent (agent utilisateur).

De plus, pour l'interopérabilité avec les agents utilisateurs hérités, il PEUT (MAY) également offrir JSONP (Remote JSON - JSONP) [jsonp] en autorisant les requêtes GET avec un paramètre supplémentaire :

callback : OPTIONAL (OPTIONNEL). Le nom qualifié d'une fonction JavaScript.

Par exemple, un client peut demander la révocation d'un jeton d'accès avec la requête suivante (les sauts de ligne sont uniquement à des fins d'affichage) :

https://example.com/revoke?token=agabcdefddddafdd&
callback=package.myCallback

Réponse réussie :

package.myCallback();

Réponse d'erreur :

package.myCallback({"error":"unsupported_token_type"});

Les clients doivent être conscients que lorsqu'ils s'appuient sur JSONP, un endpoint de révocation malveillant peut tenter d'injecter du code malveillant dans le client.