Zum Hauptinhalt springen

4. Erhalt der Autorisierung (Obtaining Authorization)

Um ein Zugangstoken (Access Token) anzufordern, erhält der Client die Autorisierung vom Ressourcenbesitzer (Resource Owner). Die Autorisierung wird in Form einer Autorisierung (Authorization Grant) ausgedrückt, die der Client verwendet, um das Zugangstoken anzufordern. OAuth definiert vier Autorisierungstypen: Autorisierungscode (Authorization Code), implizit (Implicit), Ressourcenbesitzer-Passwort-Anmeldeinformationen (Resource Owner Password Credentials) und Client-Anmeldeinformationen (Client Credentials). Es bietet auch einen Erweiterungsmechanismus zur Definition zusätzlicher Autorisierungstypen.

4.1. Autorisierungscode (Authorization Code Grant)​

Der Autorisierungscodetyp (Authorization Code Grant Type) wird verwendet, um sowohl Zugangstokens als auch Aktualisierungstokens (Refresh Token) zu erhalten, und ist für vertrauliche Clients (Confidential Client) optimiert. Da dies ein umleitungsbasierter Ablauf ist, muss (MUST) der Client in der Lage sein, mit dem Benutzeragenten des Ressourcenbesitzers (normalerweise ein Webbrowser) zu interagieren und eingehende Anfragen (über Umleitung) vom Autorisierungsserver zu empfangen.

     +----------+
     | Resource |
     |   Owner  |
     |          |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier      +---------------+
     |         -+----(A)-- & Redirection URI ---->|               |
     |  User-   |                                 | Authorization |
     |  Agent  -+----(B)-- User authenticates --->|     Server    |
     |          |                                 |               |
     |         -+----(C)-- Authorization Code ---<|               |
     +-|----|---+                                 +---------------+
       |    |                                         ^      v
      (A)  (C)                                        |      |
       |    |                                         |      |
       ^    v                                         |      |
     +---------+                                      |      |
     |         |>---(D)-- Authorization Code ---------'      |
     |  Client |          & Redirection URI                  |
     |         |                                             |
     |         |<---(E)----- Access Token -------------------'
     +---------+       (w/ Optional Refresh Token)

Abbildung 3: Autorisierungscode-Ablauf (Authorization Code Flow)

Der in Abbildung 3 dargestellte Ablauf umfasst die folgenden Schritte.

(A) Der Client initiiert den Ablauf, indem er den Benutzeragenten des Ressourcenbesitzers zum Autorisierungs-Endpunkt (Authorization Endpoint) leitet. Der Client enthält seine Client-Kennung (Client Identifier), den angeforderten Bereich (Scope), den lokalen Zustand (Local State) und einen Weiterleitungs-URI (Redirection URI), zu dem der Autorisierungsserver den Benutzeragenten zurücksendet, sobald der Zugriff gewährt oder verweigert wurde.

(B) Der Autorisierungsserver authentifiziert den Ressourcenbesitzer (über den Benutzeragenten) und ermittelt, ob der Ressourcenbesitzer die Zugriffsanforderung des Clients gewährt oder verweigert.

(C) Unter der Annahme, dass der Ressourcenbesitzer den Zugriff gewährt, leitet der Autorisierungsserver den Benutzeragenten mithilfe des zuvor bereitgestellten Weiterleitungs-URI (in der Anfrage oder während der Client-Registrierung) zum Client zurück. Der Weiterleitungs-URI enthält den Autorisierungscode (Authorization Code) und jeden zuvor vom Client bereitgestellten lokalen Zustand.

(D) Der Client fordert ein Zugangstoken vom Token-Endpunkt (Token Endpoint) des Autorisierungsservers an, indem er den im vorherigen Schritt erhaltenen Autorisierungscode einschließt. Bei der Anforderung authentifiziert sich der Client beim Autorisierungsserver. Der Client enthält den zur Verifizierung verwendeten Weiterleitungs-URI, der zum Erhalten des Autorisierungscodes verwendet wurde.

(E) Der Autorisierungsserver authentifiziert den Client, validiert den Autorisierungscode und stellt sicher, dass der empfangene Weiterleitungs-URI mit dem URI übereinstimmt, der in Schritt (C) zum Umleiten des Clients verwendet wurde. Wenn gültig, antwortet der Autorisierungsserver mit einem Zugangstoken und optional einem Aktualisierungstoken.

4.1.1. Autorisierungsanforderung (Authorization Request)​

Der Client konstruiert die Anforderungs-URI, indem er die folgenden Parameter zur Abfragekomponente der Autorisierungs-Endpunkt-URI hinzufügt, wobei das Format application/x-www-form-urlencoded verwendet wird.

response_type
Erforderlich (REQUIRED). Der Wert muss (MUST) auf „code" gesetzt werden.

client_id
Erforderlich (REQUIRED). Die Client-Kennung, wie in Abschnitt 2.2 beschrieben.

redirect_uri
Optional (OPTIONAL). Wie in Abschnitt 3.1.2 beschrieben.

scope
Optional (OPTIONAL). Der Bereich der Zugriffsanforderung, wie in Abschnitt 3.3 beschrieben.

state
Empfohlen (RECOMMENDED). Ein undurchsichtiger Wert, der vom Client verwendet wird, um den Zustand zwischen der Anforderung und dem Rückruf aufrechtzuerhalten. Der Autorisierungsserver schließt diesen Wert ein, wenn er den Benutzeragenten zum Client umleitet. Der Parameter sollte (SHOULD) verwendet werden, um Cross-Site Request Forgery zu verhindern (siehe Abschnitt 10.12).

Der Client leitet den Ressourcenbesitzer zur konstruierten URI, indem er eine HTTP-Umleitungsantwort verwendet oder andere über den Benutzeragenten des Ressourcenbesitzers verfügbare Mittel einsetzt.

4.1.2. Autorisierungsantwort (Authorization Response)​

Wenn der Ressourcenbesitzer die Zugriffsanforderung gewährt, stellt der Autorisierungsserver einen Autorisierungscode (Authorization Code) aus und liefert ihn an den Client, indem er die folgenden Parameter zur Abfragekomponente des Weiterleitungs-URI hinzufügt, wobei das Format application/x-www-form-urlencoded verwendet wird.

code
Erforderlich (REQUIRED). Der vom Autorisierungsserver generierte Autorisierungscode. Der Autorisierungscode muss (MUST) kurz nach der Ausstellung ablaufen, um das Risiko von Lecks zu mindern. Eine empfohlene maximale Lebensdauer des Autorisierungscodes beträgt 10 Minuten. Der Client darf (MUST NOT) den Autorisierungscode mehr als einmal verwenden. Wenn ein Autorisierungscode mehr als einmal verwendet wird, muss (MUST) der Autorisierungsserver die Anforderung ablehnen und sollte (SHOULD), falls möglich, alle zuvor auf der Grundlage dieses Autorisierungscodes ausgestellten Tokens widerrufen. Der Autorisierungscode ist an die Client-Kennung und den Weiterleitungs-URI gebunden.

state
Erforderlich (REQUIRED), wenn der Parameter „state" in der Client-Autorisierungsanforderung vorhanden war. Der genaue vom Client empfangene Wert.

4.1.2.1. Fehlerantwort (Error Response)​

Wenn die Anforderung fehlschlägt (der Ressourcenbesitzer verweigert den Zugriff oder die Anforderung schlägt fehl), benachrichtigt der Autorisierungsserver den Client, indem er die folgenden Parameter zur Abfragekomponente des Weiterleitungs-URI hinzufügt, wobei das Format application/x-www-form-urlencoded verwendet wird.

error
Erforderlich (REQUIRED). Ein einzelner ASCII [USASCII] Fehlercode. Einer der folgenden:

  • invalid_request - Der Anforderung fehlt ein erforderlicher Parameter, enthält einen ungültigen Parameterwert, enthält einen Parameter mehr als einmal oder ist anderweitig fehlerhaft.

  • unauthorized_client - Der Client ist nicht berechtigt, mit dieser Methode einen Autorisierungscode anzufordern.

  • access_denied - Der Ressourcenbesitzer oder Autorisierungsserver hat die Anforderung abgelehnt.

  • unsupported_response_type - Der Autorisierungsserver unterstützt das Erhalten eines Autorisierungscodes mit dieser Methode nicht.

  • invalid_scope - Der angeforderte Bereich ist ungültig, unbekannt oder fehlerhaft.

  • server_error - Der Autorisierungsserver ist auf eine unerwartete Bedingung gestoßen, die ihn daran gehindert hat, die Anforderung zu verarbeiten.

  • temporarily_unavailable - Der Autorisierungsserver ist derzeit aufgrund einer vorübergehenden Überlastung oder Serverwartung nicht in der Lage, die Anforderung zu verarbeiten.

4.1.3. Zugangstokenanforderung (Access Token Request)​

Der Client stellt eine Anforderung an den Token-Endpunkt (Token Endpoint), indem er die folgenden Parameter im HTTP-Anforderungsentitätskörper unter Verwendung des Formats application/x-www-form-urlencoded verwendet.

grant_type
Erforderlich (REQUIRED). Der Wert muss (MUST) auf „authorization_code" gesetzt werden.

code
Erforderlich (REQUIRED). Der vom Autorisierungsserver empfangene Autorisierungscode.

redirect_uri
Erforderlich (REQUIRED), wenn der Parameter „redirect_uri" in der Autorisierungsanforderung von Abschnitt 4.1.1 enthalten war, und ihre Werte müssen (MUST) identisch sein.

client_id
Erforderlich (REQUIRED), wenn der Client nicht beim Autorisierungsserver authentifiziert ist.

4.1.4. Zugangstoken-Antwort (Access Token Response)​

Wenn die Autorisierungsanforderung gültig und autorisiert ist, stellt der Autorisierungsserver ein Zugangstoken (Access Token) und ein optionales Aktualisierungstoken (Refresh Token) aus, wie in Abschnitt 5.1 beschrieben. Wenn die Anforderung fehlgeschlagen ist oder ungültig ist, gibt der Autorisierungsserver eine Fehlerantwort zurück, wie in Abschnitt 5.2 beschrieben.

4.2. Implizite Autorisierung (Implicit Grant)​

Der implizite Autorisierungstyp (Implicit Grant Type) wird verwendet, um Zugangstokens (Access Tokens) zu erhalten (er unterstützt nicht die Ausstellung von Aktualisierungstokens (Refresh Tokens)) und ist für öffentliche Clients optimiert, die bekanntermaßen einen bestimmten Weiterleitungs-URI verwenden. Diese Clients sind typischerweise in einem Browser mit einer Skriptsprache wie JavaScript implementiert.

Da dies ein umleitungsbasierter Ablauf ist, muss (MUST) der Client in der Lage sein, mit dem Benutzeragenten des Ressourcenbesitzers (normalerweise ein Webbrowser) zu interagieren und eingehende Anfragen (über Umleitung) vom Autorisierungsserver zu empfangen.

Im Gegensatz zum Autorisierungscode-Autorisierungstyp, bei dem der Client separate Anfragen für die Autorisierung und für ein Zugangstoken stellt, erhält der Client das Zugangstoken als Ergebnis der Autorisierungsanforderung.

Der implizite Autorisierungstyp umfasst keine Client-Authentifizierung und basiert auf der Anwesenheit des Ressourcenbesitzers und der Registrierung des Weiterleitungs-URI. Da das Zugangstoken in den Weiterleitungs-URI kodiert wird, kann es dem Ressourcenbesitzer und anderen Anwendungen, die auf demselben Gerät vorhanden sind, offengelegt werden.

     +----------+
     | Resource |
     |  Owner   |
     |          |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier     +---------------+
     |         -+----(A)-- & Redirection URI --->|               |
     |  User-   |                                | Authorization |
     |  Agent  -|----(B)-- User authenticates -->|     Server    |
     |          |                                |               |
     |          |<---(C)--- Redirection URI ----<|               |
     |          |          with Access Token     +---------------+
     |          |            in Fragment
     |          |                                +---------------+
     |          |----(D)--- Redirection URI ---->|   Web-Hosted  |
     |          |          without Fragment      |     Client    |
     |          |                                |    Resource   |
     |     (F)  |<---(E)------- Script ---------<|               |
     |          |                                +---------------+
     +-|--------+
       |    |
      (A)  (G) Access Token
       |    |
       ^    v
     +---------+
     |         |
     |  Client |
     |         |
     +---------+

Hinweis: Die Linien, die die Schritte (A) und (B) veranschaulichen, sind in zwei Teile unterteilt, da sie durch den Benutzeragenten verlaufen.

Abbildung 4: Impliziter Autorisierungsablauf (Implicit Grant Flow)

Der in Abbildung 4 dargestellte Ablauf umfasst die folgenden Schritte:

(A) Der Client initiiert den Ablauf, indem er den Benutzeragenten des Ressourcenbesitzers zum Autorisierungs-Endpunkt leitet. Der Client enthält seine Client-Kennung (Client Identifier), den angeforderten Bereich (Scope), den lokalen Zustand (Local State) und einen Weiterleitungs-URI (Redirection URI), zu dem der Autorisierungsserver den Benutzeragenten zurücksendet, sobald der Zugriff gewährt (oder verweigert) wurde.

(B) Der Autorisierungsserver authentifiziert den Ressourcenbesitzer (über den Benutzeragenten) und ermittelt, ob der Ressourcenbesitzer die Zugriffsanforderung des Clients gewährt oder verweigert.

(C) Unter der Annahme, dass der Ressourcenbesitzer den Zugriff gewährt, leitet der Autorisierungsserver den Benutzeragenten mithilfe des zuvor bereitgestellten Weiterleitungs-URI zum Client zurück. Der Weiterleitungs-URI enthält das Zugangstoken im URI-Fragment.

(D) Der Benutzeragent folgt den Umleitungsanweisungen, indem er eine Anfrage an die webgehostete Client-Ressource stellt (die das Fragment gemäß [RFC2616] nicht enthält). Der Benutzeragent behält die Fragmentinformationen lokal bei.

(E) Die webgehostete Client-Ressource gibt eine Webseite zurück (typischerweise ein HTML-Dokument mit einem eingebetteten Skript), die in der Lage ist, auf den vollständigen Weiterleitungs-URI zuzugreifen, einschließlich des vom Benutzeragenten beibehaltenen Fragments, und das Zugangstoken (und andere Parameter) zu extrahieren, die im Fragment enthalten sind.

(F) Der Benutzeragent führt das von der webgehosteten Client-Ressource bereitgestellte Skript lokal aus, das das Zugangstoken extrahiert.

(G) Der Benutzeragent übergibt das Zugangstoken an den Client.

Siehe Abschnitte 1.3.2 und 9 für Hintergrundinformationen zur Verwendung der impliziten Autorisierung. Siehe Abschnitte 10.3 und 10.16 für wichtige Sicherheitsüberlegungen bei der Verwendung der impliziten Autorisierung.

4.2.1. Autorisierungsanforderung (Authorization Request)​

Der Client konstruiert die Anforderungs-URI, indem er die folgenden Parameter zur Abfragekomponente der Autorisierungs-Endpunkt-URI hinzufügt.

response_type
Erforderlich (REQUIRED). Der Wert muss (MUST) auf „token" gesetzt werden.

client_id
Erforderlich (REQUIRED). Die Client-Kennung, wie in Abschnitt 2.2 beschrieben.

redirect_uri
Optional (OPTIONAL). Wie in Abschnitt 3.1.2 beschrieben.

scope
Optional (OPTIONAL). Der Bereich der Zugriffsanforderung, wie in Abschnitt 3.3 beschrieben.

state
Empfohlen (RECOMMENDED). Ein undurchsichtiger Wert, der vom Client verwendet wird, um den Zustand zwischen der Anforderung und dem Rückruf aufrechtzuerhalten.

4.2.2. Zugangstoken-Antwort (Access Token Response)​

Wenn der Ressourcenbesitzer die Zugriffsanforderung gewährt, stellt der Autorisierungsserver ein Zugangstoken (Access Token) aus und liefert es an den Client, indem er die folgenden Parameter zur Fragmentkomponente des Weiterleitungs-URI hinzufügt.

access_token
Erforderlich (REQUIRED). Das vom Autorisierungsserver ausgestellte Zugangstoken.

token_type
Erforderlich (REQUIRED). Der Tokentyp, wie in Abschnitt 7.1 beschrieben. Der Wert ist nicht case-sensitiv.

expires_in
Empfohlen (RECOMMENDED). Die Lebensdauer des Zugangstokens in Sekunden.

scope
Optional (OPTIONAL), wenn identisch mit dem vom Client angeforderten Bereich; andernfalls erforderlich (REQUIRED).

state
Erforderlich (REQUIRED), wenn der Parameter „state" in der Client-Autorisierungsanforderung vorhanden war.

4.2.2.1. Fehlerantwort (Error Response)​

Wenn die Anforderung aufgrund eines fehlenden, ungültigen oder nicht übereinstimmenden Weiterleitungs-URI fehlschlägt oder wenn die Client-Kennung fehlt oder ungültig ist, sollte (SHOULD) der Autorisierungsserver den Ressourcenbesitzer über den Fehler informieren und darf (MUST NOT) den Benutzeragenten nicht automatisch zum ungültigen Weiterleitungs-URI umleiten.

Wenn der Ressourcenbesitzer die Zugriffsanforderung verweigert oder wenn die Anforderung aus anderen Gründen als einem fehlenden oder ungültigen Weiterleitungs-URI fehlschlägt, benachrichtigt der Autorisierungsserver den Client, indem er die folgenden Parameter zur Fragmentkomponente des Weiterleitungs-URI hinzufügt, wobei das Format application/x-www-form-urlencoded gemäß Anhang B verwendet wird:

error
Erforderlich (REQUIRED). Ein einzelner ASCII [USASCII] Fehlercode aus den folgenden:

  • invalid_request - Der Anforderung fehlt ein erforderlicher Parameter, enthält einen ungültigen Parameterwert, enthält einen Parameter mehr als einmal oder ist anderweitig fehlerhaft.

  • unauthorized_client - Der Client ist nicht berechtigt, mit dieser Methode ein Zugangstoken anzufordern.

  • access_denied - Der Ressourcenbesitzer oder Autorisierungsserver hat die Anforderung abgelehnt.

  • unsupported_response_type - Der Autorisierungsserver unterstützt das Erhalten eines Zugangstokens mit dieser Methode nicht.

  • invalid_scope - Der angeforderte Bereich ist ungültig, unbekannt oder fehlerhaft.

  • server_error - Der Autorisierungsserver ist auf eine unerwartete Bedingung gestoßen, die ihn daran gehindert hat, die Anforderung zu verarbeiten. (Dieser Fehlercode ist erforderlich, da ein 500 Internal Server Error HTTP-Statuscode nicht über eine HTTP-Umleitung an den Client zurückgegeben werden kann.)

  • temporarily_unavailable - Der Autorisierungsserver ist derzeit aufgrund einer vorübergehenden Überlastung oder Serverwartung nicht in der Lage, die Anforderung zu verarbeiten. (Dieser Fehlercode ist erforderlich, da ein 503 Service Unavailable HTTP-Statuscode nicht über eine HTTP-Umleitung an den Client zurückgegeben werden kann.)

Werte für den Parameter „error" dürfen (MUST NOT) keine Zeichen außerhalb des Satzes %x20-21 / %x23-5B / %x5D-7E enthalten.

error_description
Optional (OPTIONAL). Menschenlesbarer ASCII [USASCII] Text, der zusätzliche Informationen bereitstellt, um dem Client-Entwickler zu helfen, den aufgetretenen Fehler zu verstehen. Werte für den Parameter „error_description" dürfen (MUST NOT) keine Zeichen außerhalb des Satzes %x20-21 / %x23-5B / %x5D-7E enthalten.

error_uri
Optional (OPTIONAL). Ein URI, der eine menschenlesbare Webseite mit Informationen über den Fehler identifiziert, um dem Client-Entwickler zusätzliche Informationen über den Fehler bereitzustellen. Werte für den Parameter „error_uri" müssen (MUST) der URI-Referenzsyntax entsprechen und dürfen daher (MUST NOT) keine Zeichen außerhalb des Satzes %x21 / %x23-5B / %x5D-7E enthalten.

state
Erforderlich (REQUIRED), wenn ein Parameter „state" in der Client-Autorisierungsanforderung vorhanden war. Der genaue vom Client empfangene Wert.

Beispielsweise leitet der Autorisierungsserver den Benutzeragenten um, indem er die folgende HTTP-Antwort sendet:

HTTP/1.1 302 Found
Location: https://client.example.com/cb#error=access_denied&state=xyz

4.3. Ressourcenbesitzer-Passwort-Anmeldeinformationen (Resource Owner Password Credentials Grant)​

Der Ressourcenbesitzer-Passwort-Anmeldeinformationen-Autorisierungstyp (Resource Owner Password Credentials Grant Type) ist in Fällen geeignet, in denen der Ressourcenbesitzer eine Vertrauensbeziehung mit dem Client hat, wie z. B. das Betriebssystem des Geräts oder eine hochprivilegierte Anwendung. Der Autorisierungsserver sollte (SHOULD) beim Aktivieren dieses Autorisierungstyps besondere Vorsicht walten lassen und ihn nur zulassen, wenn andere Abläufe nicht praktikabel sind.

Dieser Autorisierungstyp ist für Clients geeignet, die in der Lage sind, die Anmeldeinformationen des Ressourcenbesitzers (Benutzername und Passwort, typischerweise unter Verwendung eines interaktiven Formulars) zu erhalten. Er wird auch verwendet, um bestehende Clients, die direkte Authentifizierungsschemata wie HTTP Basic oder Digest-Authentifizierung verwenden, zu OAuth zu migrieren, indem die gespeicherten Anmeldeinformationen in ein Zugangstoken konvertiert werden.

     +----------+
     | Resource |
     |  Owner   |
     |          |
     +----------+
          v
          |    Resource Owner
         (A) Password Credentials
          |
          v
     +---------+                                  +---------------+
     |         |>--(B)---- Resource Owner ------->|               |
     |         |         Password Credentials     | Authorization |
     | Client  |                                  |     Server    |
     |         |<--(C)---- Access Token ----------|               |
     |         |    (w/ Optional Refresh Token)   |               |
     +---------+                                  +---------------+

Abbildung 5: Ressourcenbesitzer-Passwort-Anmeldeinformationen-Ablauf

Der in Abbildung 5 dargestellte Ablauf umfasst die folgenden Schritte:

(A) Der Ressourcenbesitzer stellt dem Client seinen Benutzernamen und sein Passwort zur Verfügung.

(B) Der Client fordert ein Zugangstoken vom Token-Endpunkt des Autorisierungsservers an, indem er die vom Ressourcenbesitzer erhaltenen Anmeldeinformationen einschließt. Bei der Anforderung authentifiziert sich der Client beim Autorisierungsserver.

(C) Der Autorisierungsserver authentifiziert den Client und validiert die Anmeldeinformationen des Ressourcenbesitzers und stellt, wenn gültig, ein Zugangstoken aus.

4.3.1. Autorisierungsanforderung und -antwort (Authorization Request and Response)​

Die Methode, durch die der Client die Anmeldeinformationen des Ressourcenbesitzers erhält, liegt außerhalb des Geltungsbereichs dieser Spezifikation. Der Client muss (MUST) die Anmeldeinformationen verwerfen, sobald ein Zugangstoken erhalten wurde.

4.3.2. Zugangstokenanforderung (Access Token Request)​

grant_type
Erforderlich (REQUIRED). Der Wert muss (MUST) auf „password" gesetzt werden.

username
Erforderlich (REQUIRED). Der Benutzername des Ressourcenbesitzers.

password
Erforderlich (REQUIRED). Das Passwort des Ressourcenbesitzers.

scope
Optional (OPTIONAL). Der Bereich der Zugriffsanforderung, wie in Abschnitt 3.3 beschrieben.

4.3.3. Zugangstoken-Antwort (Access Token Response)​

Wenn die Zugangstokenanforderung gültig und autorisiert ist, stellt der Autorisierungsserver ein Zugangstoken und ein optionales Aktualisierungstoken aus, wie in Abschnitt 5.1 beschrieben. Wenn die Anforderung die Client-Authentifizierung fehlgeschlagen ist oder ungültig ist, gibt der Autorisierungsserver eine Fehlerantwort zurück, wie in Abschnitt 5.2 beschrieben.

Ein Beispiel für eine erfolgreiche Antwort:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

4.4. Client-Anmeldeinformationen (Client Credentials Grant)​

Der Client kann (MAY) ein Zugangstoken (Access Token) nur auf der Grundlage seiner Client-Anmeldeinformationen (Client Credentials) (oder anderer unterstützter Authentifizierungsmittel) anfordern, wenn der Client den Zugriff auf geschützte Ressourcen unter seiner Kontrolle oder auf Ressourcen eines anderen Ressourcenbesitzers anfordert, die zuvor mit dem Autorisierungsserver vereinbart wurden (die Methode hierfür liegt außerhalb des Geltungsbereichs dieser Spezifikation).

Der Client-Anmeldeinformationen-Autorisierungstyp darf (MUST) nur von vertraulichen Clients (Confidential Clients) verwendet werden.

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(A)- Client Authentication --->| Authorization |
     | Client  |                                  |     Server    |
     |         |<--(B)---- Access Token ----------|               |
     |         |                                  |               |
     +---------+                                  +---------------+

Abbildung 6: Client-Anmeldeinformationen-Ablauf (Client Credentials Flow)

Der in Abbildung 6 dargestellte Ablauf umfasst die folgenden Schritte:

(A) Der Client authentifiziert sich beim Autorisierungsserver und fordert ein Zugangstoken vom Token-Endpunkt an.

(B) Der Autorisierungsserver authentifiziert den Client und stellt, wenn gültig, ein Zugangstoken aus.

4.4.1. Autorisierungsanforderung und -antwort (Authorization Request and Response)​

Da die Client-Authentifizierung als Autorisierung verwendet wird, ist keine zusätzliche Autorisierungsanforderung erforderlich.

4.4.2. Zugangstokenanforderung (Access Token Request)​

Der Client stellt eine Anforderung an den Token-Endpunkt (Token Endpoint), indem er die folgenden Parameter im HTTP-Anforderungsentitätskörper unter Verwendung des Formats application/x-www-form-urlencoded gemäß Anhang B mit UTF-8-Zeichenkodierung hinzufügt:

grant_type
Erforderlich (REQUIRED). Der Wert muss (MUST) auf „client_credentials" gesetzt werden.

scope
Optional (OPTIONAL). Der Bereich der Zugriffsanforderung, wie in Abschnitt 3.3 beschrieben.

Der Client muss (MUST) sich beim Autorisierungsserver authentifizieren, wie in Abschnitt 3.2.1 beschrieben.

4.4.3. Zugangstoken-Antwort (Access Token Response)​

Wenn die Zugangstokenanforderung gültig und autorisiert ist, stellt der Autorisierungsserver ein Zugangstoken aus, wie in Abschnitt 5.1 beschrieben. Ein Aktualisierungstoken sollte (SHOULD NOT) nicht eingeschlossen werden. Wenn die Anforderung die Client-Authentifizierung fehlgeschlagen ist oder ungültig ist, gibt der Autorisierungsserver eine Fehlerantwort zurück, wie in Abschnitt 5.2 beschrieben.

Ein Beispiel für eine erfolgreiche Antwort:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "example_parameter":"example_value"
}

4.5. Erweiterungsautorisierungen (Extension Grants)​

Der Client verwendet einen Erweiterungsautorisierungstyp (Extension Grant Type), indem er den Autorisierungstyp unter Verwendung eines absoluten URI (definiert vom Autorisierungsserver) als Wert des Parameters „grant_type" des Token-Endpunkts angibt und indem er alle erforderlichen zusätzlichen Parameter hinzufügt.

Beispielsweise könnte der Client die folgende HTTP-Anforderung unter Verwendung von TLS stellen, um ein Zugangstoken unter Verwendung eines Security Assertion Markup Language (SAML) 2.0 Assertion Grant Type, wie durch [OAuth-SAML2] definiert, anzufordern (mit zusätzlichen Zeilenumbrüchen nur für Anzeigezwecke):

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-
bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU
[...der Kürze halber weggelassen...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24-

Wenn die Zugangstokenanforderung gültig und autorisiert ist, stellt der Autorisierungsserver ein Zugangstoken und ein optionales Aktualisierungstoken aus, wie in Abschnitt 5.1 beschrieben. Wenn die Anforderung die Client-Authentifizierung fehlgeschlagen ist oder ungültig ist, gibt der Autorisierungsserver eine Fehlerantwort zurück, wie in Abschnitt 5.2 beschrieben.

Letztes Update am