Zum Hauptinhalt springen

5. Ausstellung eines Zugangstokens (Issuing an Access Token)

Wenn die Zugangstokenanforderung gültig und autorisiert ist, stellt der Autorisierungsserver (Authorization Server) ein Zugangstoken (Access Token) und ein optionales Aktualisierungstoken (Refresh Token) aus, wie in Abschnitt 5.1 beschrieben. Wenn die Anforderung die Client-Authentifizierung nicht bestanden hat oder ungültig ist, gibt der Autorisierungsserver eine Fehlerantwort zurück, wie in Abschnitt 5.2 beschrieben.

5.1. Erfolgreiche Antwort (Successful Response)​

Der Autorisierungsserver stellt ein Zugangstoken (Access Token) und ein optionales Aktualisierungstoken (Refresh Token) aus und konstruiert die Antwort, indem er die folgenden Parameter zum Entitätskörper der HTTP-Antwort mit einem 200 (OK) Statuscode hinzufügt.

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

token_type
Erforderlich (REQUIRED). Der Typ des ausgestellten Tokens, wie in Abschnitt 7.1 beschrieben. Der Wert ist nicht case-sensitiv.

expires_in
Empfohlen (RECOMMENDED). Die Lebensdauer des Zugangstokens in Sekunden. Beispielsweise gibt der Wert „3600" an, dass das Zugangstoken eine Stunde nach Generierung der Antwort abläuft. Wenn weggelassen, sollte (SHOULD) der Autorisierungsserver die Ablaufzeit über andere Mittel bereitstellen oder den Standardwert dokumentieren.

refresh_token
Optional (OPTIONAL). Das Aktualisierungstoken (Refresh Token), das verwendet werden kann, um neue Zugangstokens unter Verwendung derselben Autorisierung (Authorization Grant) zu erhalten, wie in Abschnitt 6 beschrieben.

scope
Optional (OPTIONAL), wenn identisch mit dem vom Client angeforderten Bereich; andernfalls erforderlich (REQUIRED). Der Bereich des Zugangstokens, wie in Abschnitt 3.3 beschrieben.

Die Parameter sind im Entitätskörper der HTTP-Antwort unter Verwendung des Medientyps application/json, wie in [RFC4627] definiert, enthalten. Die Parameter werden in eine JavaScript Object Notation (JSON)-Struktur serialisiert, indem jeder Parameter auf der höchsten Strukturebene hinzugefügt wird. Parameternamen und Zeichenfolgenwerte sind als JSON-Zeichenfolgen enthalten. Numerische Werte sind als JSON-Zahlen enthalten. Die Reihenfolge der Parameter spielt keine Rolle und kann variieren.

Der Autorisierungsserver muss (MUST) das HTTP-„Cache-Control"-Antwortheaderfeld [RFC2616] mit einem Wert von „no-store" in jeder Antwort einschließen, die Tokens, Anmeldeinformationen oder andere sensible Informationen enthält, sowie das „Pragma"-Antwortheaderfeld [RFC2616] mit einem Wert von „no-cache".

Zum Beispiel:

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

Der Client muss (MUST) nicht erkannte Wertnamen in der Antwort ignorieren. Die Größen von Tokens und anderen vom Autorisierungsserver empfangenen Werten bleiben undefiniert. Der Client sollte (SHOULD) vermeiden, Annahmen über Wertgrößen zu treffen. Der Autorisierungsserver sollte (SHOULD) die Größe aller von ihm ausgestellten Werte dokumentieren.

5.2. Fehlerantwort (Error Response)​

Der Autorisierungsserver antwortet mit einem HTTP 400 (Bad Request) Statuscode (sofern nicht anders angegeben) und schließt die folgenden Parameter in die Antwort ein.

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

  • invalid_request - Der Anforderung fehlt ein erforderlicher Parameter, sie enthält einen nicht unterstützten Parameterwert (außer dem Autorisierungstyp), wiederholt einen Parameter, enthält mehrere Anmeldeinformationen, verwendet mehr als einen Mechanismus zur Authentifizierung des Clients oder ist anderweitig fehlerhaft.

  • invalid_client - Die Client-Authentifizierung ist fehlgeschlagen (z. B. unbekannter Client, keine Client-Authentifizierung eingeschlossen oder nicht unterstützte Authentifizierungsmethode). Der Autorisierungsserver kann (MAY) einen HTTP 401 (Unauthorized) Statuscode zurückgeben, um die vom Client unterstützten HTTP-Authentifizierungsschemata anzuzeigen. Wenn der Client versucht hat, sich über das HTTP Basic-Authentifizierungsschema zu authentifizieren, darf (MUST NOT) der Autorisierungsserver keinen HTTP 401 (Unauthorized) Statuscode zurückgeben.

  • invalid_grant - Die bereitgestellte Autorisierung (Authorization Grant) (z. B. Autorisierungscode (Authorization Code), Ressourcenbesitzer-Anmeldeinformationen (Resource Owner Credentials)) oder das Aktualisierungstoken (Refresh Token) ist ungültig, abgelaufen, widerrufen, stimmt nicht mit dem in der Autorisierungsanforderung verwendeten Weiterleitungs-URI überein oder wurde für einen anderen Client ausgestellt.

  • unauthorized_client - Der authentifizierte Client ist nicht berechtigt, diesen Autorisierungstyp (Authorization Grant Type) zu verwenden.

  • unsupported_grant_type - Der Autorisierungstyp wird vom Autorisierungsserver nicht unterstützt.

  • invalid_scope - Der angeforderte Bereich ist ungültig, unbekannt, fehlerhaft oder überschreitet den vom Ressourcenbesitzer gewährten Bereich.

Parameterwerte dürfen (MUST NOT) 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. Wird verwendet, um dem Client-Entwickler zu helfen, den Fehler zu verstehen. Parameterwerte dürfen (MUST NOT) 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. Wird verwendet, um dem Client-Entwickler zusätzliche Informationen über den Fehler bereitzustellen. Parameterwerte müssen (MUST) der in [RFC3986] Abschnitt 2 definierten URI-Referenzsyntax entsprechen und dürfen (MUST NOT) Zeichen außerhalb des Satzes %x21 / %x23-5B / %x5D-7E enthalten.

Die Parameter sind im Entitätskörper der HTTP-Antwort unter Verwendung des Medientyps application/json, wie in [RFC4627] definiert, enthalten. Die Parameter werden in eine JavaScript Object Notation (JSON)-Struktur serialisiert, indem jeder Parameter auf der höchsten Strukturebene hinzugefügt wird. Parameternamen und Zeichenfolgenwerte sind als JSON-Zeichenfolgen enthalten. Numerische Werte sind als JSON-Zahlen enthalten. Die Reihenfolge der Parameter spielt keine Rolle und kann variieren.

Zum Beispiel:

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

{
  "error":"invalid_request"
}
Letztes Update am