2. Token-Austauschanforderung und -Antwort

2.1. Anforderung

Ein Client fordert ein Sicherheitstoken an, indem er eine Token-Anforderung an den Token-Endpunkt des Autorisierungsservers unter Verwendung des in Abschnitt 4.5 von [RFC6749] definierten Erweiterungs-Grant-Typ-Mechanismus stellt.

Die Client-Authentifizierung gegenüber dem Autorisierungsserver erfolgt unter Verwendung der von OAuth 2.0 bereitgestellten normalen Mechanismen. Abschnitt 2.3.1 von [RFC6749] definiert die passwortbasierte Authentifizierung des Clients, die Client-Authentifizierung ist jedoch erweiterbar und andere Mechanismen sind möglich. [RFC7523] definiert beispielsweise die Client-Authentifizierung unter Verwendung von Bearer JSON Web Tokens (JWTs) [JWT]. Die unterstützten Methoden der Client-Authentifizierung und ob nicht authentifizierte oder nicht identifizierte Clients zugelassen werden, sind Bereitstellungsentscheidungen, die im Ermessen des Autorisierungsservers liegen. Beachten Sie, dass das Weglassen der Client-Authentifizierung es jedem, der ein kompromittiertes Token besitzt, ermöglicht, ein kompromittiertes Token über einen STS in andere Tokens umzuwandeln. Daher ermöglicht die Client-Authentifizierung zusätzliche Autorisierungsprüfungen durch den STS, welche Entitäten berechtigt sind, andere Entitäten zu imitieren oder Delegierungen von diesen zu erhalten.

Der Client stellt eine Token-Austauschanforderung an den Token-Endpunkt mit einem Erweiterungs-Grant-Typ unter Verwendung der HTTP-"POST"-Methode. Die folgenden Parameter sind im HTTP-Anforderungs-Entity-Body im Format "application/x-www-form-urlencoded" mit einer Zeichenkodierung von UTF-8, wie in Anhang B von [RFC6749] beschrieben, enthalten.

grant_type ERFORDERLICH (REQUIRED). Der Wert urn:ietf:params:oauth:grant-type:token-exchange gibt an, dass ein Token-Austausch durchgeführt wird.

resource OPTIONAL. Ein URI, der den Zieldienst oder die Zielressource angibt, wo der Client das angeforderte Sicherheitstoken verwenden möchte. Dies ermöglicht es dem Autorisierungsserver, Richtlinien entsprechend dem Ziel anzuwenden, wie z. B. die Bestimmung von Typ und Inhalt des auszustellenden Tokens oder ob und wie das Token verschlüsselt werden soll. In vielen Fällen hat ein Client keine Kenntnis von der logischen Organisation der Systeme, mit denen er interagiert, und kennt nur einen URI des Dienstes, bei dem er das Token verwenden möchte. Der Parameter resource ermöglicht es dem Client, dem Autorisierungsserver anzuzeigen, wo er das ausgestellte Token verwenden möchte, indem er den Ort, typischerweise als https-URL, in der Token-Austauschanforderung in derselben Form angibt, die für den Zugriff auf diese Ressource verwendet wird. Der Autorisierungsserver verfügt normalerweise über die Fähigkeit, von einem Ressourcen-URI-Wert auf eine geeignete Richtlinie abzubilden. Der Wert des Parameters resource MUSS ein absoluter URI sein, wie in Abschnitt 4.3 von [RFC3986] spezifiziert, der eine Abfragekomponente enthalten KANN und KEINE Fragmentkomponente enthalten DARF. Mehrere resource-Parameter können verwendet werden, um anzuzeigen, dass das ausgestellte Token bei den mehreren aufgeführten Ressourcen verwendet werden soll. Siehe [OAUTH-RESOURCE] für zusätzliche Hintergründe und Verwendungen des Parameters resource.

audience OPTIONAL. Der logische Name des Zieldienstes, bei dem der Client das angeforderte Sicherheitstoken verwenden möchte. Dies dient einem ähnlichen Zweck wie der Parameter resource, wobei der Client jedoch einen logischen Namen für den Zieldienst angibt. Die Interpretation des Namens erfordert, dass der Wert etwas ist, das sowohl der Client als auch der Autorisierungsserver verstehen. Ein OAuth-Client-Identifier, ein SAML-Entity-Identifier [OASIS.saml-core-2.0-os] und ein OpenID Connect Issuer Identifier [OpenID.Core] sind Beispiele für Dinge, die als audience-Parameterwerte verwendet werden könnten. audience-Werte, die mit einem bestimmten Autorisierungsserver verwendet werden, müssen jedoch innerhalb dieses Servers eindeutig sein, um sicherzustellen, dass sie ordnungsgemäß als der beabsichtigte Werttyp interpretiert werden. Mehrere audience-Parameter können verwendet werden, um anzuzeigen, dass das ausgestellte Token bei den mehreren aufgeführten Zielgruppen verwendet werden soll. Die Parameter audience und resource können zusammen verwendet werden, um mehrere Zieldienste mit einer Mischung aus logischen Namen und Ressourcen-URIs anzuzeigen.

scope OPTIONAL. Eine Liste von durch Leerzeichen getrennten, groß- und kleinschreibungssensitiven Zeichenfolgen, wie in Abschnitt 3.3 von [RFC6749] definiert, die es dem Client ermöglichen, den gewünschten Geltungsbereich des angeforderten Sicherheitstokens im Kontext des Dienstes oder der Ressource anzugeben, bei dem/der das Token verwendet wird. Die Werte und die zugehörige Semantik des Geltungsbereichs sind dienstspezifisch und sollten in der entsprechenden Dienstdokumentation beschrieben werden.

requested_token_type OPTIONAL. Ein Bezeichner, wie in Abschnitt 3 beschrieben, für den Typ des angeforderten Sicherheitstokens. Wenn der angeforderte Typ nicht spezifiziert ist, liegt der ausgestellte Token-Typ im Ermessen des Autorisierungsservers und kann durch Kenntnis der Anforderungen des durch den Parameter resource oder audience angezeigten Dienstes oder der Ressource diktiert werden.

subject_token ERFORDERLICH (REQUIRED). Ein Sicherheitstoken, das die Identität der Partei repräsentiert, in deren Namen die Anforderung gestellt wird. Typischerweise ist das Subjekt dieses Tokens das Subjekt des Sicherheitstokens, das als Antwort auf die Anforderung ausgestellt wird.

subject_token_type ERFORDERLICH (REQUIRED). Ein Bezeichner, wie in Abschnitt 3 beschrieben, der den Typ des Sicherheitstokens im Parameter subject_token angibt.

actor_token OPTIONAL. Ein Sicherheitstoken, das die Identität der handelnden Partei repräsentiert. Typischerweise ist dies die Partei, die autorisiert ist, das angeforderte Sicherheitstoken zu verwenden und im Namen des Subjekts zu handeln.

actor_token_type Ein Bezeichner, wie in Abschnitt 3 beschrieben, der den Typ des Sicherheitstokens im Parameter actor_token angibt. Dies ist ERFORDERLICH, wenn der Parameter actor_token in der Anforderung enthalten ist, DARF jedoch andernfalls NICHT enthalten sein.

Bei der Verarbeitung der Anforderung MUSS der Autorisierungsserver die geeigneten Validierungsverfahren für den angegebenen Token-Typ durchführen und, falls das Akteur-Token vorhanden ist, auch die geeigneten Validierungsverfahren für dessen angegebenen Token-Typ durchführen. Die Gültigkeitskriterien und Details eines bestimmten Tokens gehen über den Rahmen dieses Dokuments hinaus und sind spezifisch für den jeweiligen Token-Typ und seinen Inhalt.

In Ermangelung einer Einmalnutzung oder anderer für den Token-Typ spezifischer Semantiken hat der Akt der Durchführung eines Token-Austauschs keine Auswirkungen auf die Gültigkeit des Subjekt-Tokens oder Akteur-Tokens. Darüber hinaus ist der Austausch ein einmaliges Ereignis und stellt keine enge Verknüpfung zwischen den Eingabe- und Ausgabetokens her, so dass (z. B.) während die Ablaufzeit des Ausgabetokens durch die des Eingabetokens beeinflusst werden kann, nicht erwartet wird, dass sich eine Erneuerung oder Verlängerung des Eingabetokens in den Eigenschaften des Ausgabetokens widerspiegelt. Es kann dennoch angemessen oder wünschenswert sein, Token-Widerrufsereignisse weiterzugeben. Dies ist jedoch keine allgemeine Eigenschaft des STS-Protokolls und wäre spezifisch für eine bestimmte Implementierung, einen bestimmten Token-Typ oder eine bestimmte Bereitstellung.

2.1.1. Beziehung zwischen Ressource, Zielgruppe und Geltungsbereich

Bei der Anforderung eines Tokens kann der Client den/die gewünschten Zieldienst(e), bei dem/denen er dieses Token verwenden möchte, über die Parameter audience und resource angeben sowie den gewünschten Geltungsbereich des angeforderten Tokens über den Parameter scope angeben. Die Semantik einer solchen Anforderung ist, dass der Client ein Token mit dem angeforderten Geltungsbereich anfordert, das bei allen angeforderten Zieldiensten verwendbar ist. Effektiv sind die angeforderten Zugriffsrechte des Tokens das kartesische Produkt aller Geltungsbereiche bei allen Zieldiensten.

Ein Autorisierungsserver ist möglicherweise nicht bereit oder nicht in der Lage, eine Token-Anforderung zu erfüllen, aber die Wahrscheinlichkeit einer nicht erfüllbaren Anforderung ist deutlich höher, wenn sehr weitreichende Zugriffsrechte angefordert werden. Daher sollten Clients in Ermangelung spezifischer Kenntnisse über die Beziehung von Systemen in einer Bereitstellung bei der Breite des angeforderten Zugriffs, insbesondere bei der Anzahl der Zieldienste, Zurückhaltung üben. Ein Autorisierungsserver kann den in Abschnitt 2.2.2 definierten Fehlercode invalid_target verwenden, um einen Client darüber zu informieren, dass er gleichzeitig Zugriff auf zu viele Zieldienste angefordert hat.

2.2. Antwort

Der Autorisierungsserver antwortet auf eine Token-Austauschanforderung mit einer normalen OAuth 2.0-Antwort vom Token-Endpunkt, wie in Abschnitt 5 von [RFC6749] spezifiziert. Zusätzliche Details und Erklärungen werden in den folgenden Unterabschnitten bereitgestellt.

2.2.1. Erfolgreiche Antwort

Wenn die Anforderung gültig ist und alle Richtlinien und sonstigen Kriterien des Autorisierungsservers erfüllt, wird eine erfolgreiche Token-Antwort erstellt, indem die folgenden Parameter dem Entity-Body der HTTP-Antwort unter Verwendung des Medientyps "application/json", wie von [RFC8259] spezifiziert, und einem HTTP-Statuscode 200 hinzugefügt werden. Die Parameter werden in eine JavaScript Object Notation (JSON)-Struktur serialisiert, indem jeder Parameter auf der obersten Ebene hinzugefügt wird. Parameternamen und Zeichenfolgenwerte werden als JSON-Zeichenfolgen aufgenommen. Numerische Werte werden als JSON-Zahlen aufgenommen. Die Reihenfolge der Parameter spielt keine Rolle und kann variieren.

access_token ERFORDERLICH (REQUIRED). Das vom Autorisierungsserver als Antwort auf die Token-Austauschanforderung ausgestellte Sicherheitstoken. Der Parameter access_token aus Abschnitt 5.1 von [RFC6749] wird hier verwendet, um das angeforderte Token zu transportieren, was es diesem Token-Austauschprotokoll ermöglicht, die für den Token-Endpunkt definierten bestehenden OAuth 2.0-Anforderungs- und Antwortkonstrukte zu verwenden. Der Bezeichner access_token wird aus historischen Gründen verwendet, und das ausgestellte Token muss kein OAuth-Zugriffstoken sein.

issued_token_type ERFORDERLICH (REQUIRED). Ein Bezeichner, wie in Abschnitt 3 beschrieben, für die Darstellung des ausgestellten Sicherheitstokens.

token_type ERFORDERLICH (REQUIRED). Ein nicht zwischen Groß- und Kleinschreibung unterscheidender Wert, der die Methode zur Verwendung des ausgestellten Zugriffstokens angibt, wie in Abschnitt 7.1 von [RFC6749] spezifiziert. Er liefert dem Client Informationen darüber, wie das Zugriffstoken für den Zugriff auf geschützte Ressourcen genutzt werden kann. Ein Wert von "Bearer", wie in [RFC6750] spezifiziert, gibt beispielsweise an, dass das ausgestellte Sicherheitstoken ein Bearer-Token ist und der Client es einfach so vorlegen kann, wie es ist, ohne zusätzlichen Anspruchsnachweis über den Inhalt des Tokens selbst hinaus. Beachten Sie, dass die Bedeutung dieses Parameters von der Bedeutung des Parameters issued_token_type verschieden ist, der die Darstellung des ausgestellten Sicherheitstokens deklariert; der Begriff "Token-Typ" wird typischerweise verwendet, um die strukturelle oder syntaktische Darstellung des Sicherheitstokens zu bezeichnen, wie dies bei allen *_token_type-Parametern in dieser Spezifikation der Fall ist. Wenn das ausgestellte Token kein Zugriffstoken ist oder nicht als Zugriffstoken verwendbar ist, dann wird der Wert token_type "N_A" verwendet, um anzuzeigen, dass ein OAuth 2.0-token_type-Bezeichner in diesem Kontext nicht anwendbar ist.

expires_in EMPFOHLEN (RECOMMENDED). Die Gültigkeitsdauer in Sekunden des vom Autorisierungsserver ausgestellten Tokens. Oftmals hat der Client nicht die Neigung oder Fähigkeit, den Inhalt des Tokens zu prüfen, und dieser Parameter bietet einen konsistenten und Token-Typ-agnostischen Hinweis darauf, wie lange das Token voraussichtlich gültig sein wird. Zum Beispiel bedeutet der Wert 1800, dass das Token in dreißig Minuten ab dem Zeitpunkt der Antwortgenerierung abläuft.

scope OPTIONAL, wenn der Geltungsbereich des ausgestellten Sicherheitstokens identisch mit dem vom Client angeforderten Geltungsbereich ist; andernfalls ist er ERFORDERLICH.

refresh_token OPTIONAL. Ein Refresh-Token wird typischerweise nicht ausgestellt, wenn der Austausch von einem temporären Berechtigungsnachweis (dem subject_token) gegen einen anderen temporären Berechtigungsnachweis (das ausgestellte Token) zur Verwendung in einem anderen Kontext erfolgt. Ein Refresh-Token kann in Fällen ausgestellt werden, in denen der Client des Token-Austauschs die Fähigkeit benötigt, auf eine Ressource zuzugreifen, selbst wenn der ursprüngliche Berechtigungsnachweis nicht mehr gültig ist (z. B. Szenarien, in denen der Benutzer nicht anwesend ist oder offline ist, wo kein Benutzer mehr eine aktive Sitzung mit dem Client unterhält). Profile oder Bereitstellungen dieser Spezifikation sollten die Bedingungen klar dokumentieren, unter denen ein Client ein Refresh-Token als Antwort auf Anforderungen mit dem Grant-Typ urn:ietf:params:oauth:grant-type:token-exchange erwarten sollte.

2.2.2. Fehlerantwort

Wenn die Anforderung selbst nicht gültig ist oder wenn entweder das subject_token oder actor_token aus irgendeinem Grund ungültig sind oder aufgrund von Richtlinien inakzeptabel sind, MUSS der Autorisierungsserver eine Fehlerantwort erstellen, wie in Abschnitt 5.2 von [RFC6749] spezifiziert. Der Wert des Parameters error MUSS der Fehlercode invalid_request sein.

Wenn der Autorisierungsserver nicht bereit oder nicht in der Lage ist, ein Token für einen beliebigen durch die Parameter resource oder audience angezeigten Zieldienst auszustellen, SOLLTE der Fehlercode invalid_target in der Fehlerantwort verwendet werden.

Der Autorisierungsserver KANN zusätzliche Informationen bezüglich der Gründe für den Fehler unter Verwendung von error_description aufnehmen, wie in Abschnitt 5.2 von [RFC6749] erörtert.

Andere Fehlercodes können ebenfalls verwendet werden, sofern angemessen.

2.3. Beispiel für Token-Austausch

Das folgende Beispiel demonstriert einen hypothetischen Token-Austausch, bei dem ein OAuth-Ressourcenserver während des Austauschs die Rolle des Clients übernimmt. Er tauscht ein Zugriffstoken, das er in einer Anforderung an eine geschützte Ressource erhalten hat, gegen ein neues Token ein, das er für den Aufruf eines Backend-Dienstes verwendet (zusätzliche Zeilenumbrüche und Einrückungen in den Beispielen dienen nur zu Darstellungszwecken).

Abbildung 1 zeigt, wie der Ressourcenserver eine Anforderung an eine geschützte Ressource empfängt, die ein OAuth-Zugriffstoken im Authorization-Header enthält, wie in Abschnitt 2.1 von [RFC6750] spezifiziert.

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

Abbildung 1: Anforderung an geschützte Ressource

In Abbildung 2 übernimmt der Ressourcenserver die Rolle des Clients für den Token-Austausch, und das Zugriffstoken aus der Anforderung in Abbildung 1 wird unter Verwendung einer Anforderung, wie in Abschnitt 2.1 spezifiziert, an den Autorisierungsserver gesendet. Der Wert des Parameters subject_token trägt das Zugriffstoken, und der Wert des Parameters subject_token_type gibt an, dass es sich um ein OAuth 2.0-Zugriffstoken handelt. Der Ressourcenserver, der in der Rolle des Clients handelt, verwendet seinen Bezeichner und sein Geheimnis, um sich gegenüber dem Autorisierungsserver unter Verwendung des HTTP-Basic-Authentifizierungsschemas zu authentifizieren. Der Parameter resource gibt den Ort des Backend-Dienstes an, <https://backend.example.com/api>, wo das ausgestellte Token verwendet wird.

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

Abbildung 2: Token-Austauschanforderung

Der Autorisierungsserver validiert die Client-Anmeldeinformationen und das in der Token-Austauschanforderung präsentierte subject_token. Aus dem Parameter resource ist der Autorisierungsserver in der Lage, die geeignete Richtlinie zu bestimmen, die auf die Anforderung angewendet werden soll, und stellt ein Token aus, das für die Verwendung unter <https://backend.example.com> geeignet ist. Der Parameter access_token der in Abbildung 3 gezeigten Antwort enthält das neue Token, das selbst ein Bearer-OAuth-Zugriffstoken ist, das für eine Minute gültig ist. Das Token ist zufällig ein JWT; seine Struktur und sein Format sind für den Client jedoch undurchsichtig, sodass der issued_token_type nur angibt, dass es sich um ein Zugriffstoken handelt.

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
}

Abbildung 3: Token-Austauschantwort

Der Ressourcenserver kann dann das neu erworbene Zugriffstoken verwenden, um eine Anforderung an den Backend-Server zu stellen, wie in Abbildung 4 illustriert.

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

Abbildung 4: Backend-Anforderung an geschützte Ressource

Zusätzliche Beispiele finden sich in Anhang A.