Überbringer-Token-Typ

Antwort auf Zugriffstoken

Erfolgreiche Antwort

Wenn die Anforderung eines Zugriffstokens gültig ist, muss der Autorisierungsserver ein Zugriffstoken (und ein optionales Aktualisierungstoken) generieren und diese an den Client zurückgeben, in der Regel zusammen mit einigen zusätzlichen Eigenschaften zur Autorisierung.

Die Antwort mit einem Zugriffstoken sollte die folgenden Eigenschaften enthalten:

  • (erforderlich) Die Zugriffstokenzeichenfolge, wie sie vom Autorisierungsserver ausgegeben wird.
  • (erforderlich) Der Typ des Tokens, um den es sich handelt, in der Regel nur die Zeichenfolge "Bearer".
  • (empfohlen) Wenn das Zugriffstoken abläuft, sollte der Server mit der Dauer antworten, für die das Zugriffstoken gewährt wurde.
  • (optional) Wenn das Zugriffstoken abläuft, ist es nützlich, ein Aktualisierungstoken zurückzugeben, das Anwendungen zum Abrufen eines anderen Zugriffstokens verwenden können. Aber Token, die mit der impliziten Berechtigung ausgestellt wurden, können nicht als Aktualisierungstoken ausgestellt werden.
  • (optional) Wenn der vom Benutzer gewährte Bereich mit dem von der App angeforderten Bereich identisch ist, ist dieser Parameter optional. Wenn sich der gewährte Bereich vom angeforderten Bereich unterscheidet, z. B. wenn der Benutzer den Bereich geändert hat, ist dieser Parameter erforderlich.

Wenn der Server mit einem Zugriffstoken antwortet, muss er auch den zusätzlichen HTTP-Header einschließen, um sicherzustellen, dass Clients diese Anforderung nicht zwischenspeichern.

Eine erfolgreiche Tokenantwort kann z. B. wie folgt aussehen:

HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3", "token_type":"Bearer", "expires_in":3600, "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk", "scope":"create" }

Zugriffstoken

Das Format für OAuth 2.0-Bearertoken wird in einer separaten Spezifikation, RFC 6750, beschrieben. Es gibt keine definierte Struktur für das Token, die von der Spezifikation benötigt wird, sodass Sie eine Zeichenfolge generieren und Token nach Belieben implementieren können. Die gültigen Zeichen in einem Bearertoken sind alphanumerisch und die folgenden Satzzeichen:

-._~+/

Eine einfache Implementierung von Bearertoken besteht darin, eine zufällige Zeichenfolge zu generieren und sie zusammen mit den zugehörigen Benutzer- und Bereichsinformationen in einer Datenbank zu speichern, oder fortschrittlichere Systeme können selbstcodierte Token verwenden, bei denen die Tokenzeichenfolge selbst alle erforderlichen Informationen enthält.

Nicht erfolgreiche Antwort

Wenn die Zugriffstokenanforderung ungültig ist, z. B. wenn die Umleitungs-URL nicht mit der während der Autorisierung verwendeten URL übereinstimmt, muss der Server eine Fehlerantwort zurückgeben.

Fehlerantworten werden mit einem HTTP 400-Statuscode zurückgegeben (sofern nicht anders angegeben andernfalls) mit und Parametern. Der Parameter ist immer einer der unten aufgeführten Werte.

  • – In der Anforderung fehlt ein Parameter, sodass der Server mit der Anforderung nicht fortfahren kann. Dies kann auch zurückgegeben werden, wenn die Anforderung einen nicht unterstützten Parameter enthält oder einen Parameter wiederholt.
  • – Fehler bei der Clientauthentifizierung, z. B. wenn die Anforderung eine ungültige Client-ID oder einen ungültigen geheimen Schlüssel enthält. Senden Sie in diesem Fall eine HTTP 401-Antwort.
  • – Der Autorisierungscode (oder das Kennwort des Benutzers für den Kennworterteilungstyp) ist ungültig oder abgelaufen. Dies ist auch der Fehler, den Sie zurückgeben würden, wenn die in der Autorisierungsgewährung angegebene Umleitungs-URL nicht mit der URL übereinstimmt, die in dieser Zugriffstokenanforderung angegeben wird.
  • – Bei Zugriffstokenanforderungen, die einen Bereich (Kennwort oder client_credentials gewähren) enthalten, weist dieser Fehler auf einen ungültigen Bereichswert in der Anforderung hin.
  • – Dieser Client ist nicht berechtigt, den angeforderten Grant-Typ zu verwenden. Wenn Sie z. B. einschränken, welche Anwendungen die implizite Gewährung verwenden können, geben Sie diesen Fehler für die anderen Apps zurück.
  • – Wenn ein Berechtigungstyp angefordert wird, den der Autorisierungsserver nicht erkennt, verwenden Sie diesen Code. Beachten Sie, dass unbekannte Bewilligungstypen auch diesen speziellen Fehlercode anstelle des oben genannten verwenden.

Es gibt zwei optionale Parameter, wenn eine Fehlerantwort zurückgegeben wird, und . Diese sollen Entwicklern mehr Informationen über den Fehler geben, die nicht für Endbenutzer gedacht sind. Denken Sie jedoch daran, dass viele Entwickler diesen Fehlertext direkt an die Endbenutzer weitergeben, egal wie sehr Sie sie warnen, daher ist es eine gute Idee, sicherzustellen, dass er auch für die Endbenutzer zumindest etwas hilfreich ist.

Der Parameter darf nur ASCII-Zeichen enthalten und sollte höchstens ein oder zwei Sätze umfassen, die die Umstände des Irrtums. Dies ist ein großartiger Ort, um einen Link zu Ihrer API-Dokumentation zu erstellen, um Informationen darüber zu erhalten, wie Sie den aufgetretenen Fehler beheben können.

Die gesamte Fehlerantwort wird als JSON-Zeichenfolge zurückgegeben, ähnlich wie bei der erfolgreichen Antwort. Nachfolgend finden Sie ein Beispiel für eine Fehlerantwort.

HTTP/1.1 400 Ungültige Anfrage Content-Type: application/json Cache-Control: no-store { "error": "invalid_request", "error_description": "Bei der Anforderung fehlte der Parameter 'redirect_uri'.", "error_uri": "Die vollständige API-Dokumentation finden Sie unter https://authorization-server.com/docs/access_token" }