2. Introspection Endpoint (Introspektionsendpunkt)

Der Introspektionsendpunkt ist ein OAuth 2.0-Endpunkt, der einen Parameter entgegennimmt, der ein OAuth 2.0-Token darstellt, und ein JSON [RFC7159]-Dokument zurückgibt, das die Metainformationen rund um das Token darstellt, einschließlich der Information, ob dieses Token derzeit aktiv ist. Die Definition eines aktiven Tokens hängt vom Autorisierungsserver ab, aber im Allgemeinen handelt es sich dabei um ein Token, das von diesem Autorisierungsserver ausgestellt wurde, nicht abgelaufen ist, nicht widerrufen wurde und für die Verwendung bei der geschützten Ressource gültig ist, die den Introspektionsaufruf durchführt.

Der Introspektionsendpunkt MUSS durch einen Transportschichtsicherheitsmechanismus geschützt werden, wie in Abschnitt 4 beschrieben. Die Mittel, mit denen die geschützte Ressource den Ort des Introspektionsendpunkts entdeckt, liegen außerhalb des Geltungsbereichs dieser Spezifikation.

2.1. Introspection Request (Introspektionsanforderung)

Die geschützte Ressource ruft den Introspektionsendpunkt mithilfe einer HTTP-POST-Anforderung [RFC7231] auf, wobei Parameter als "application/x-www-form-urlencoded"-Daten gesendet werden, wie in [W3C.REC-html5-20141028] definiert. Die geschützte Ressource sendet einen Parameter, der das Token darstellt, sowie optionale Parameter, die zusätzlichen Kontext darstellen, der der geschützten Ressource bekannt ist, um den Autorisierungsserver bei seiner Antwort zu unterstützen.

token : ERFORDERLICH (REQUIRED). Der Zeichenfolgenwert des Tokens. Bei Zugriffstokens ist dies der "access_token"-Wert, der vom in OAuth 2.0 [RFC6749], Abschnitt 5.1, definierten Token-Endpunkt zurückgegeben wird. Bei Aktualisierungstokens ist dies der "refresh_token"-Wert, der vom in OAuth 2.0 [RFC6749], Abschnitt 5.1, definierten Token-Endpunkt zurückgegeben wird. Andere Token-Typen liegen außerhalb des Geltungsbereichs dieser Spezifikation.

token_type_hint : OPTIONAL. Ein Hinweis auf den Typ des zur Introspektion übermittelten Tokens. Die geschützte Ressource KANN (MAY) diesen Parameter übergeben, um dem Autorisierungsserver zu helfen, die Token-Suche zu optimieren. Wenn der Server das Token anhand des gegebenen Hinweises nicht finden kann, MUSS (MUST) er seine Suche auf alle 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. Werte für dieses Feld sind im Register "OAuth Token Type Hints" definiert, das in OAuth Token Revocation [RFC7009] definiert ist.

Der Introspektionsendpunkt KANN (MAY) andere OPTIONALE Parameter akzeptieren, um der Abfrage weiteren Kontext bereitzustellen. Beispielsweise könnte ein Autorisierungsserver die IP-Adresse des Clients wissen wollen, der auf die geschützte Ressource zugreift, um festzustellen, ob es wahrscheinlich ist, dass der richtige Client das Token vorlegt. Die Definition dieses oder anderer Parameter liegt außerhalb des Geltungsbereichs dieser Spezifikation und muss durch Dienstdokumentation oder Erweiterungen dieser Spezifikation definiert werden. Wenn der Autorisierungsserver nicht in der Lage ist, den Zustand des Tokens ohne zusätzliche Informationen zu bestimmen, SOLLTE (SHOULD) er eine Introspektionsantwort zurückgeben, die angibt, dass das Token nicht aktiv ist, wie in Abschnitt 2.2 beschrieben.

Um Token-Scanning-Angriffe zu verhindern, MUSS (MUST) der Endpunkt auch eine Form der Autorisierung für den Zugriff auf diesen Endpunkt verlangen, wie z. B. Client-Authentifizierung wie in OAuth 2.0 [RFC6749] beschrieben oder ein separates OAuth 2.0-Zugriffstoken wie das Bearer-Token, das in OAuth 2.0 Bearer Token Usage [RFC6750] beschrieben ist. Die Methoden zur Verwaltung und Validierung dieser Authentifizierungsdaten liegen außerhalb des Geltungsbereichs dieser Spezifikation.

Das Folgende zeigt beispielsweise, wie eine geschützte Ressource den Token-Introspektionsendpunkt aufruft, um Informationen zu einem OAuth 2.0-Bearer-Token abzufragen. Die geschützte Ressource verwendet ein separates OAuth 2.0-Bearer-Token, um diesen Aufruf zu autorisieren.

Das Folgende ist eine nicht-normative Beispielanforderung:

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

In diesem Beispiel verwendet die geschützte Ressource eine Client-ID und ein Client-Geheimnis, um sich gegenüber dem Introspektionsendpunkt zu authentifizieren. Die geschützte Ressource sendet auch einen Token-Typ-Hinweis, der angibt, dass sie Informationen zu einem Zugriffstoken abfragt.

Das Folgende ist eine nicht-normative Beispielanforderung:

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 (Introspektionsantwort)

Der Server antwortet mit einem JSON-Objekt [RFC7159] im Format "application/json" mit den folgenden Top-Level-Mitgliedern.

active : ERFORDERLICH (REQUIRED). Boolescher Indikator, ob das vorgelegte Token derzeit aktiv ist oder nicht. Die Besonderheiten des Zustands "active" eines Tokens variieren je nach Implementierung des Autorisierungsservers und den Informationen, die er über seine Tokens speichert, aber ein Rückgabewert von "true" für die Eigenschaft "active" zeigt im Allgemeinen an, dass ein bestimmtes Token von diesem Autorisierungsserver ausgestellt wurde, nicht vom Ressourcenbesitzer widerrufen wurde und innerhalb seines gegebenen Gültigkeitszeitfensters liegt (z. B. nach seiner Ausstellungszeit und vor seiner Ablaufzeit). Siehe Abschnitt 4 für Informationen zur Implementierung solcher Prüfungen.

scope : OPTIONAL. Eine JSON-Zeichenfolge, die eine durch Leerzeichen getrennte Liste von Scopes enthält, die diesem Token zugeordnet sind, in dem in Abschnitt 3.3 von OAuth 2.0 [RFC6749] beschriebenen Format.

client_id : OPTIONAL. Client-Identifikator des OAuth 2.0-Clients, der dieses Token angefordert hat.

username : OPTIONAL. Menschenlesbarer Identifikator für den Ressourcenbesitzer, der dieses Token autorisiert hat.

token_type : OPTIONAL. Typ des Tokens, wie in Abschnitt 5.1 von OAuth 2.0 [RFC6749] definiert.

exp : OPTIONAL. Ganzzahliger Zeitstempel, gemessen in der Anzahl der Sekunden seit dem 1. Januar 1970 UTC, der angibt, wann dieses Token abläuft, wie in JWT [RFC7519] definiert.

iat : OPTIONAL. Ganzzahliger Zeitstempel, gemessen in der Anzahl der Sekunden seit dem 1. Januar 1970 UTC, der angibt, wann dieses Token ursprünglich ausgestellt wurde, wie in JWT [RFC7519] definiert.

nbf : OPTIONAL. Ganzzahliger Zeitstempel, gemessen in der Anzahl der Sekunden seit dem 1. Januar 1970 UTC, der angibt, vor welchem Zeitpunkt dieses Token nicht verwendet werden darf, wie in JWT [RFC7519] definiert.

sub : OPTIONAL. Subjekt des Tokens, wie in JWT [RFC7519] definiert. Normalerweise ein maschinenlesbarer Identifikator des Ressourcenbesitzers, der dieses Token autorisiert hat.

aud : OPTIONAL. Dienstspezifischer Zeichenfolgenidentifikator oder Liste von Zeichenfolgenidentifikatoren, die die beabsichtigte Zielgruppe für dieses Token darstellen, wie in JWT [RFC7519] definiert.

iss : OPTIONAL. Zeichenfolge, die den Aussteller dieses Tokens darstellt, wie in JWT [RFC7519] definiert.

jti : OPTIONAL. Zeichenfolgenidentifikator für das Token, wie in JWT [RFC7519] definiert.

Spezifische Implementierungen KÖNNEN (MAY) diese Struktur mit ihren eigenen dienstspezifischen Antwortnamen als Top-Level-Mitglieder dieses JSON-Objekts erweitern. Antwortnamen, die über Domänen hinweg verwendet werden sollen, MÜSSEN (MUST) im Register "OAuth Token Introspection Response", das in Abschnitt 3.1 definiert ist, registriert werden.

Der Autorisierungsserver KANN (MAY) unterschiedlich auf verschiedene geschützte Ressourcen antworten, die dieselbe Anforderung stellen. Beispielsweise KANN (MAY) ein Autorisierungsserver einschränken, welche Scopes von einem bestimmten Token für jede geschützte Ressource zurückgegeben werden, um zu verhindern, dass eine geschützte Ressource mehr über das größere Netzwerk erfährt, als für ihren Betrieb erforderlich ist.

Die Antwort KANN (MAY) von der geschützten Ressource zwischengespeichert werden, um die Leistung zu verbessern und die Last auf dem Introspektionsendpunkt zu verringern, jedoch auf Kosten der Aktualität der Informationen, die von der geschützten Ressource für Autorisierungsentscheidungen verwendet werden. Siehe Abschnitt 4 für weitere Informationen zum Kompromiss, wenn die Antwort zwischengespeichert wird.

Die folgende Antwort enthält beispielsweise eine Reihe von Informationen über ein aktives Token:

Das Folgende ist eine nicht-normative Beispielantwort:

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"
}

Wenn der Introspektionsaufruf ordnungsgemäß autorisiert ist, das Token jedoch nicht aktiv ist, auf diesem Server nicht existiert oder die geschützte Ressource dieses bestimmte Token nicht introspektieren darf, dann MUSS (MUST) der Autorisierungsserver eine Introspektionsantwort zurückgeben, bei der das Feld "active" auf "false" gesetzt ist. Beachten Sie: Um zu vermeiden, dass zu viel vom Zustand des Autorisierungsservers an Dritte preisgegeben wird, SOLLTE (SHOULD) der Autorisierungsserver KEINE zusätzlichen Informationen über ein inaktives Token enthalten, einschließlich des Grundes, warum das Token inaktiv ist.

Das Folgende ist eine nicht-normative Beispielantwort für ein Token, das widerrufen wurde oder anderweitig ungültig ist:

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

{
 "active": false
}

2.3. Error Response (Fehlerantwort)

Wenn die geschützte Ressource OAuth 2.0-Client-Anmeldeinformationen verwendet, um sich gegenüber dem Introspektionsendpunkt zu authentifizieren, und ihre Anmeldeinformationen ungültig sind, antwortet der Autorisierungsserver mit einem HTTP 401 (Unauthorized), wie in Abschnitt 5.2 von OAuth 2.0 [RFC6749] beschrieben.

Wenn die geschützte Ressource ein OAuth 2.0-Bearer-Token verwendet, um ihren Aufruf an den Introspektionsendpunkt zu autorisieren, und das zur Autorisierung verwendete Token keine ausreichenden Berechtigungen enthält oder für diese Anforderung anderweitig ungültig ist, antwortet der Autorisierungsserver mit einem HTTP 401-Code, wie in Abschnitt 3 von OAuth 2.0 Bearer Token Usage [RFC6750] beschrieben.

Beachten Sie, dass eine ordnungsgemäß formatierte und autorisierte Abfrage für ein inaktives oder anderweitig ungültiges Token (oder ein Token, über das die geschützte Ressource nichts wissen darf) von dieser Spezifikation nicht als Fehlerantwort betrachtet wird. In diesen Fällen MUSS (MUST) der Autorisierungsserver stattdessen mit einer Introspektionsantwort antworten, bei der das Feld "active" auf "false" gesetzt ist, wie in Abschnitt 2.2 beschrieben.