2. Token Revocation (Token-Widerruf)

Implementierungen MÜSSEN (MUST) den Widerruf von Aktualisierungstoken unterstützen und SOLLTEN (SHOULD) den Widerruf von Zugriffstoken unterstützen (siehe Implementierungshinweis).

Der Client fordert den Widerruf eines bestimmten Tokens an, indem er eine HTTP-POST-Anforderung an die URL des Token-Widerrufsendpunkts sendet. Diese URL MUSS (MUST) den in [RFC6749], Abschnitt 3.1, angegebenen Regeln entsprechen. Clients MÜSSEN (MUST) überprüfen, ob die URL eine HTTPS-URL ist.

Die Mittel zum Erhalten des Standorts des Widerrufsendpunkts liegen außerhalb des Geltungsbereichs dieser Spezifikation. Beispielsweise kann der Client-Entwickler die Dokumentation des Servers konsultieren oder es kann eine automatische Erkennung verwendet werden. Da dieser Endpunkt Sicherheitsanmeldeinformationen verarbeitet, muss der Endpunktstandort aus einer vertrauenswürdigen Quelle bezogen werden.

Da Anforderungen an den Token-Widerrufsendpunkt zur Übertragung von Klartext-Anmeldeinformationen in der HTTP-Anforderung führen, MÜSSEN (MUST) URLs für Token-Widerrufsendpunkte HTTPS-URLs sein. Der Autorisierungsserver MUSS (MUST) Transport Layer Security (TLS) [RFC5246] in einer Version verwenden, die mit [RFC6749], Abschnitt 1.6, konform ist. Implementierungen KÖNNEN (MAY) auch zusätzliche Transportschicht-Sicherheitsmechanismen unterstützen, die ihre Sicherheitsanforderungen erfüllen.

Wenn der Host des Token-Widerrufsendpunkts auch über HTTP erreicht werden kann, SOLLTE (SHOULD) der Server auch einen Widerrufsdienst unter der entsprechenden HTTP-URI anbieten, aber er DARF diese URI NICHT (MUST NOT) als Token-Widerrufsendpunkt veröffentlichen. Dies stellt sicher, dass versehentlich über HTTP gesendete Token widerrufen werden.

2.1. Revocation Request (Widerrufsanforderung)

Der Client erstellt die Anforderung, indem er die folgenden Parameter unter Verwendung des Formats "application/x-www-form-urlencoded" in den HTTP-Anforderungstextkörper aufnimmt:

token : REQUIRED (ERFORDERLICH). Das Token, das der Client widerrufen lassen möchte.

token_type_hint : OPTIONAL (OPTIONAL). Ein Hinweis auf den Typ des zum Widerruf eingereichten Tokens. Clients KÖNNEN (MAY) diesen Parameter übergeben, um dem Autorisierungsserver zu helfen, die Token-Suche zu optimieren. Wenn der Server das Token anhand des angegebenen Hinweises nicht finden kann, MUSS (MUST) er seine Suche auf alle seine unterstützten Token-Typen ausdehnen. Ein Autorisierungsserver KANN (MAY) diesen Parameter ignorieren, insbesondere wenn er in der Lage ist, den Token-Typ automatisch zu erkennen. Diese Spezifikation definiert zwei solcher Werte:

access_token: Ein Zugriffstoken, wie in [RFC6749], Abschnitt 1.4 definiert
refresh_token: Ein Aktualisierungstoken, wie in [RFC6749], Abschnitt 1.5 definiert

Spezifische Implementierungen, Profile und Erweiterungen dieser Spezifikation KÖNNEN (MAY) andere Werte für diesen Parameter unter Verwendung der in Abschnitt 4.1.2 definierten Registrierung definieren.

Der Client fügt auch seine Authentifizierungsanmeldeinformationen hinzu, wie in Abschnitt 2.3 von [RFC6749] beschrieben.

Beispielsweise kann ein Client den Widerruf eines Aktualisierungstokens mit der folgenden Anforderung anfordern:

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

Der Autorisierungsserver validiert zuerst die Client-Anmeldeinformationen (im Falle eines vertraulichen Clients) und überprüft dann, ob das Token an den Client ausgegeben wurde, der die Widerrufsanforderung stellt. Wenn diese Validierung fehlschlägt, wird die Anforderung abgelehnt und der Client wird vom Autorisierungsserver wie unten beschrieben über den Fehler informiert.

Im nächsten Schritt macht der Autorisierungsserver das Token ungültig. Die Ungültigmachung erfolgt sofort, und das Token kann nach dem Widerruf nicht mehr verwendet werden. In der Praxis kann es zu einer Ausbreitungsverzögerung kommen, bei der beispielsweise einige Server über die Ungültigmachung Bescheid wissen, andere jedoch nicht. Implementierungen sollten dieses Fenster minimieren, und Clients dürfen nicht versuchen, das Token nach Erhalt einer HTTP-200-Antwort vom Server zu verwenden.

Abhängig von der Widerrufsrichtlinie des Autorisierungsservers kann der Widerruf eines bestimmten Tokens den Widerruf verwandter Token und der zugrunde liegenden Autorisierungszuteilung verursachen. Wenn das bestimmte Token ein Aktualisierungstoken ist und der Autorisierungsserver den Widerruf von Zugriffstoken unterstützt, SOLLTE (SHOULD) der Autorisierungsserver auch alle Zugriffstoken auf der Grundlage derselben Autorisierungszuteilung ungültig machen (siehe Implementierungshinweis). Wenn das an die Anforderung übergebene Token ein Zugriffstoken ist, KANN (MAY) der Server das entsprechende Aktualisierungstoken ebenfalls widerrufen.

Hinweis: Ein mit [RFC6749] konformer Client muss darauf vorbereitet sein, unerwartete Token-Ungültigmachung jederzeit zu verarbeiten. Unabhängig von dem in diesem Dokument angegebenen Widerrufsmechanismus können Ressourcenbesitzer Autorisierungszuteilungen widerrufen oder der Autorisierungsserver kann Token ungültig machen, um Sicherheitsbedrohungen zu mindern. Daher sollte es keine Interoperabilitätsprobleme darstellen, wenn unterschiedliche Serverrichtlinien in Bezug auf den kaskadierenden Widerruf von Token vorhanden sind.

2.2. Revocation Response (Widerrufsantwort)

Der Autorisierungsserver antwortet mit dem HTTP-Statuscode 200, wenn das Token erfolgreich widerrufen wurde oder wenn der Client ein ungültiges Token übermittelt hat.

Hinweis: Ungültige Token führen nicht zu einer Fehlerantwort, da der Client einen solchen Fehler nicht auf vernünftige Weise behandeln kann. Darüber hinaus ist der Zweck der Widerrufsanforderung, das Ungültigmachen des bestimmten Tokens, bereits erreicht.

Der Inhalt des Antwortkörpers wird vom Client ignoriert, da alle notwendigen Informationen im Antwortcode übermittelt werden.

Ein ungültiger Token-Typhinweiswert wird vom Autorisierungsserver ignoriert und beeinflusst die Widerrufsantwort nicht.

2.2.1. Error Response (Fehlerantwort)

Die Fehlerdarstellung entspricht der Definition in Abschnitt 5.2 von [RFC6749]. Der folgende zusätzliche Fehlercode ist für den Token-Widerrufsendpunkt definiert:

unsupported_token_type : Der Autorisierungsserver unterstützt den Widerruf des präsentierten Token-Typs nicht. Das heißt, der Client hat versucht, ein Zugriffstoken auf einem Server zu widerrufen, der diese Funktion nicht unterstützt.

Wenn der Server mit dem HTTP-Statuscode 503 antwortet, muss der Client annehmen, dass das Token noch existiert, und kann es nach einer angemessenen Verzögerung erneut versuchen. Der Server kann einen "Retry-After"-Header in die Antwort aufnehmen, um anzugeben, wie lange der Dienst für den anfragenden Client voraussichtlich nicht verfügbar sein wird.

2.3. Cross-Origin Support (Cross-Origin-Unterstützung)

Der Widerrufsendpunkt KANN (MAY) Cross-Origin Resource Sharing (CORS) [W3C.WD-cors-20120403] unterstützen, wenn er für die Verwendung in Kombination mit user-agent-basierten Anwendungen vorgesehen ist.

Darüber hinaus KANN (MAY) er zur Interoperabilität mit Legacy-User-Agents auch JSONP (Remote JSON - JSONP) [jsonp] anbieten, indem er GET-Anforderungen mit einem zusätzlichen Parameter zulässt:

callback : OPTIONAL (OPTIONAL). Der qualifizierte Name einer JavaScript-Funktion.

Beispielsweise kann ein Client den Widerruf eines Zugriffstokens mit der folgenden Anforderung anfordern (Zeilenumbrüche dienen nur zu Anzeigezwecken):

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

Erfolgreiche Antwort:

package.myCallback();

Fehlerantwort:

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

Clients sollten sich bewusst sein, dass ein böswilliger Widerrufsendpunkt beim Verlassen auf JSONP versuchen kann, bösartigen Code in den Client einzuschleusen.