OAuth 2.0 für mobile und Desktop-Apps

In diesem Dokument wird erläutert, wie Desktopanwendungen (z. B. Anwendungen, die unter Windows, macOS oder Linux ausgeführt werden, oder Befehlszeilentools) die OAuth 2.0-Endpunkte von Google verwenden, um den Zugriff auf die YouTube Data API zu autorisieren.

OAuth 2.0 ermöglicht Nutzern, bestimmte Daten für eine Anwendung freizugeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Eine Anwendung kann beispielsweise OAuth 2.0 verwenden, um die Berechtigung zum Hochladen von Videos auf den YouTube-Kanal eines Nutzers zu erhalten.

Desktopanwendungen werden lokal auf dem Computer eines Nutzers installiert (z. B. eigenständige Desktopsoftware, CLI-Tools für Entwickler, Dienstprogramme für die Hintergrundsynchronisierung oder Skripts). Da diese Apps auf einzelne Geräte verteilt werden, wird davon ausgegangen, dass sie keine Geheimnisse bewahren können (sie sind öffentliche Clients). Sie können auf Google APIs zugreifen, während der Nutzer aktiv mit der App interagiert oder wenn die App im Hintergrund ausgeführt wird.

Dieser Autorisierungsablauf ähnelt dem für Webserveranwendungen. Der Hauptunterschied besteht darin, dass Desktop-Apps den Systembrowser öffnen und einen lokalen Weiterleitungs-URI (z. B. eine Loopback-IP-Adresse) angeben müssen, um Antworten vom Autorisierungsserver von Google zu verarbeiten.

Bibliotheken und Beispiele

Wir empfehlen, die Google API-Clientbibliotheken für Ihre Programmiersprache (z.B. Python, Java, Node.js, Go, .NET) zu verwenden, wenn Sie OAuth 2.0 für Desktopanwendungen implementieren. Die Clientbibliotheken übernehmen die Nutzerautorisierung und die Tokenverwaltung. Dadurch ist die Implementierung einfacher und weniger fehleranfällig als die direkte Verwendung der HTTP/REST-Endpunkte auf niedrigerer Ebene.

Informationen zu mobilen Apps finden Sie in den Autorisierungsleitfäden für Android und iOS.

Informationen zu Apps, die auf Geräten ausgeführt werden, die keinen Systembrowser unterstützen oder nur eingeschränkte Eingabemöglichkeiten bieten, z. B. Fernseher, Spielekonsolen, Kameras oder Drucker, finden Sie unter OAuth 2.0 für Fernseher und Geräte oder Anmeldung auf Fernsehern und Geräten mit eingeschränkter Eingabe.

Vorbereitung

Die APIs für Ihr Projekt aktivieren

Für jede Anwendung, die Google APIs aufruft, müssen diese APIs in der API Console aktiviert werden.

So aktivieren Sie eine API für Ihr Projekt:

1. Öffnen Sie die API-Bibliothek in der Google API Console.
2. Wählen Sie ein Projekt aus oder erstellen Sie ein neues, wenn Sie dazu aufgefordert werden.
3. Suchen Sie auf der Seite Bibliothek nach der YouTube Data API und aktivieren Sie sie. Suchen Sie nach anderen APIs, die Ihre Anwendung verwendet, und aktivieren Sie diese ebenfalls.

Anmeldedaten für die Autorisierung erstellen

Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, muss über Autorisierungsdaten verfügen, mit denen sie sich gegenüber dem OAuth 2.0-Server von Google identifiziert. In den folgenden Schritten wird beschrieben, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann mit den Anmeldedaten auf APIs zugreifen, die Sie für dieses Projekt aktiviert haben.

1. Rufen Sie die Seite „Clients“ auf.
2. Klicken Sie auf Client erstellen.
3. Wählen Sie den Anwendungstyp Desktop-Anwendung aus.
4. Geben Sie im Feld Name einen Namen für den OAuth-Client ein. Dieser Name wird auf der Seite „Clients“ Ihres Projekts angezeigt, um den Client zu identifizieren.
5. Klicken Sie auf Erstellen.

Ihre Client-ID und Ihr Clientschlüssel werden generiert und in der Google Cloud Console angezeigt. Desktop-Anwendungen sind öffentliche Clients und können keine vertraulichen Informationen geheim halten. Verwenden Sie immer PKCE (Proof Key for Code Exchange), wenn Sie Autorisierungscodes anfordern.

Zugriffsbereiche identifizieren

Mit Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Außerdem können Nutzer so den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Es kann also eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit geben, dass die Nutzereinwilligung erteilt wird.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche ermitteln, für die Ihre App Zugriffsberechtigungen benötigt.

Die YouTube Data API v3 verwendet die folgenden Bereiche:

Das Dokument OAuth 2.0-API-Bereiche enthält eine vollständige Liste der Bereiche, die Sie für den Zugriff auf Google APIs verwenden können.

OAuth 2.0-Zugriffstokens abrufen

In den folgenden Schritten wird gezeigt, wie Ihre Anwendung mit dem OAuth 2.0-Server von Google interagiert, um die Einwilligung eines Nutzers einzuholen, eine API-Anfrage im Namen des Nutzers auszuführen. Ihre Anwendung muss diese Einwilligung einholen, bevor sie eine Google API-Anfrage ausführen kann, für die eine Nutzerautorisierung erforderlich ist.

Schritt 1: Code-Verifier und Challenge generieren

Google unterstützt das PKCE-Protokoll (Proof Key for Code Exchange), um den Ablauf für installierte Apps sicherer zu machen. Für jede Autorisierungsanfrage wird ein eindeutiger Code-Verifier erstellt. Der transformierte Wert, der als „code_challenge“ bezeichnet wird, wird an den Autorisierungsserver gesendet, um den Autorisierungscode zu erhalten.

Code-Verifier erstellen

Ein code_verifier ist ein kryptografischer Zufallsstring mit hoher Entropie, der die nicht reservierten Zeichen [A-Z] / [a-z] / [0-9] / „-“ / „.“ / „_“ / „~“ verwendet und eine Mindestlänge von 43 Zeichen und eine maximale Länge von 128 Zeichen hat.

Der Code-Verifier sollte genügend Entropie haben, damit es unmöglich ist, den Wert zu erraten.

Code-Challenge erstellen

Es werden zwei Methoden zum Erstellen der Code-Anfrage unterstützt.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Schritt 2: Anfrage an den OAuth 2.0-Server von Google senden

Wenn Sie die Nutzerautorisierung einholen möchten, senden Sie eine Anfrage an den Autorisierungsserver von Google unter https://accounts.google.com/o/oauth2/v2/auth. Dieser Endpunkt verarbeitet die Suche nach aktiven Sitzungen, authentifiziert den Nutzer und holt die Nutzereinwilligung ein. Der Endpunkt ist nur über SSL zugänglich und lehnt HTTP-Verbindungen (ohne SSL) ab.

Der Autorisierungsserver unterstützt die folgenden Abfragestringparameter für installierte Anwendungen:

Beispiel-Autorisierungs-URLs

Auf den Tabs unten finden Sie Beispiel-Autorisierungs-URLs für die verschiedenen Weiterleitungs-URI-Optionen.

Die URLs sind bis auf den Wert des Parameters redirect_uri identisch. Die URLs enthalten auch die erforderlichen Parameter response_type und client_id sowie den optionalen Parameter state. Jede URL enthält Zeilenumbrüche und Leerzeichen, um die Lesbarkeit zu verbessern.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Schritt 3: Google fordert den Nutzer auf, seine Einwilligung zu erteilen

In diesem Schritt entscheidet der Nutzer, ob er Ihrer Anwendung den angeforderten Zugriff gewährt. In dieser Phase zeigt Google ein Zustimmungsfenster an, in dem der Name Ihrer Anwendung und die Google API-Dienste, für die sie mit den Autorisierungsdaten des Nutzers Zugriff anfordert, sowie eine Zusammenfassung der zu gewährenden Zugriffsbereiche aufgeführt sind. Der Nutzer kann dann zustimmen, den Zugriff auf einen oder mehrere von Ihrer Anwendung angeforderte Bereiche zu gewähren, oder die Anfrage ablehnen.

Ihre Anwendung muss in dieser Phase nichts tun, während sie auf die Antwort des OAuth 2.0-Servers von Google wartet, die angibt, ob Zugriff gewährt wurde. Diese Antwort wird im folgenden Schritt erläutert.

Schritt 4: OAuth 2.0-Serverantwort verarbeiten

Wie Ihre Anwendung die Autorisierungsantwort erhält, hängt vom verwendeten Weiterleitungs-URI-Schema ab. Unabhängig vom Schema enthält die Antwort entweder einen Autorisierungscode (code) oder einen Fehler (error). error=access_denied gibt beispielsweise an, dass der Nutzer die Anfrage abgelehnt hat.

Wenn der Nutzer Ihrer Anwendung Zugriff gewährt, können Sie den Autorisierungscode gegen ein Zugriffstoken und ein Aktualisierungstoken austauschen, wie im nächsten Schritt beschrieben.

Schritt 5: Autorisierungscode gegen Aktualisierungs- und Zugriffstokens austauschen

Wenn Sie einen Autorisierungscode gegen ein Zugriffstoken eintauschen möchten, rufen Sie den Endpunkt https://oauth2.googleapis.com/token auf und legen Sie die folgenden Parameter fest:

Die Verwendung von DPoP ist optional, wird aber für mehr Sicherheit empfohlen. Die Sicherheit von DPoP beruht darauf, dass der private Schlüssel auf ein einzelnes Gerät beschränkt ist. Wir empfehlen, ihn so zu speichern, dass er nicht vom Gerät kopiert werden kann, z. B. mithilfe von TPMs, Secure Enclaves oder anderen hardwaregestützten Schlüsselspeichern. Wenn Sie DPoP verwenden möchten, muss Ihre Anwendung für jede Anfrage an den Token-Endpunkt ein neues, eindeutiges DPoP-Proof-JWT generieren und als HTTP-Anfrageheader hinzufügen.

Das folgende Snippet zeigt eine Beispielanfrage:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

DPoP-Proof erstellen

In den folgenden Schritten wird gezeigt, wie Sie einen DPoP-Proof mit OpenSSL über die Befehlszeile erstellen:

1. Generieren Sie ein EC-P-256-Schlüsselpaar:

   openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
   openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

2. DPoP-Header erstellen:

   Der Header muss die Anforderungen typ, alg und jwk (öffentlicher Schlüssel) enthalten. Die Werte x und y sind die Base64Url-codierten Koordinaten Ihres öffentlichen EC-Schlüssels. Codieren Sie diesen JSON-Code mit Base64Url:

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. DPoP-Nutzlast erstellen:

   Die Nutzlast muss jti (eine eindeutige Kennung für die Anfrage), htm (HTTP-Methode, z.B. POST), htu (HTTP-URI, z.B. https://oauth2.googleapis.com/token) und iat (Ausstellungszeitpunkt) enthalten. Wenn Sie vom Server in einem DPoP-Nonce-Header in der Antwort auf eine vorherige Anfrage eine Nonce erhalten haben, müssen Sie diesen Nonce-Wert in eine nonce-Anforderung einfügen. Der Nonce-Anspruch ist für den Austausch von Autorisierungscodes optional und wird nur verwendet, wenn der DPoP-Nonce-Header zuvor empfangen wurde. Codieren Sie diesen JSON-Code mit Base64Url:

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   Der Wert jti hängt vom Typ der Anzeigenplattform ab:

   • Bei Autorisierungscode-Austauschen muss der jti der Base64Url-codierte SHA256-Hash des Autorisierungscodes sein: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
   • Für den Austausch von Aktualisierungstokens muss die jti eine eindeutige Kennung pro Anfrage sein: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
4. Nachweis signieren:

   Verketten Sie den codierten Header und die Nutzlast mit einem Punkt (.) und signieren Sie das Ergebnis dann mit Ihrem privaten Schlüssel mithilfe von ES256. Beachten Sie, dass die Signatur für JWS in einem unformatierten, verketteten R | S-Format vorliegen muss (64 Byte für P-256). Wenn Sie OpenSSL direkt verwenden, müssen Sie die standardmäßige ASN.1-DER-codierte Signatur in dieses Rohformat konvertieren.

Ein erfolgreicher Austausch wird durch eine 200 OK-Antwort mit den Tokens angezeigt. Wenn während des Austauschs ein gültiger DPoP-Nachweis verwendet wird, ist das von Google zurückgegebene Aktualisierungstoken per DPoP an Ihren Schlüssel gebunden, Zugriffstokens jedoch nicht. Zugriffstokens behalten den token_type von Bearer anstelle von DPoP bei. Außerdem gibt Google in der Antwort einen DPoP-Nonce-HTTP-Header zurück. Ihr Client muss diese Nonce im Cache speichern und sie in nachfolgenden Anfragen (z. B. beim Austausch eines Aktualisierungstokens gegen ein neues Zugriffstoken oder beim Aufrufen von DPoP-geschützten APIs) in den nonce-Claim des DPoP-Proofs einfügen. Durch die Verwendung dieser frühzeitig ausgegebenen Nonce können Sie einen zusätzlichen Roundtrip-Fehler (use_dpop_nonce) bei Ihrer nächsten Anfrage vermeiden.

DPoP-Nachweise müssen für Tokenaustauschanfragen enthalten sein, die mit DPoP-gebundenen Aktualisierungstokens gestellt werden.

Ein fehlgeschlagener Austausch tritt auf, wenn der Header DPoP fehlt, obwohl er erwartet wird, ungültig ist oder wenn der Nachweis einen anderen Schlüssel als den an das Token gebundenen Schlüssel verwendet. In diesen Fällen gibt der Server den Fehler 400 Bad Request zurück. Wenn der DPoP-Proof nicht übereinstimmende htm- oder htu-Ansprüche, einen abgelaufenen iat, einen wiederverwendeten jti oder eine ungültige Signatur enthält, gibt Google den Fehlercode invalid_dpop_proof zurück. Wenn eine DPoP-Nonce erforderlich ist, z. B. während eines Aktualisierungstoken-Austauschs, und im DPoP-Proof ein nonce-Claim fehlt oder der Nonce-Wert für den Server nicht akzeptabel ist (z. B. abgelaufen, bereits verwendet oder falsch), gibt Google den Fehlercode use_dpop_nonce zusammen mit dem HTTP-Header DPoP-Nonce zurück, der eine neue Nonce enthält, die Sie in einer nachfolgenden Anfrage verwenden können. Bei anderen Fehlern wird möglicherweise invalid_grant zurückgegeben.

Google antwortet auf diese Anfrage mit einem JSON-Objekt, das ein kurzlebiges Zugriffstoken und ein Aktualisierungstoken enthält.

Die Antwort umfasst die folgenden Felder:

Das folgende Snippet zeigt ein Beispiel für erfolgreiche Antwortheader und einen Antworttext, wenn DPoP verwendet wird:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Schritt 6: Prüfen, welche Bereiche Nutzer gewährt haben

Wenn Sie mehrere Berechtigungen (Bereiche) anfordern, gewähren Nutzer Ihrer App möglicherweise nicht Zugriff auf alle. In deiner App muss geprüft werden, welche Bereiche tatsächlich gewährt wurden. Außerdem müssen Situationen, in denen einige Berechtigungen verweigert werden, ordnungsgemäß behandelt werden. In der Regel werden dazu die Funktionen deaktiviert, die auf diesen verweigerten Bereichen basieren.

Es gibt allerdings Ausnahmen. Bei Google Workspace Enterprise-Apps mit domainweiter Übertragung von Befugnissen oder Apps, die als Vertrauenswürdig gekennzeichnet sind, wird der Zustimmungsbildschirm für detaillierte Berechtigungen umgangen. Für diese Apps wird Nutzern der Bildschirm für die Einwilligung in detaillierte Berechtigungen nicht angezeigt. Stattdessen erhält Ihre App entweder alle angeforderten Bereiche oder keine.

Weitere Informationen finden Sie unter Umgang mit detaillierten Berechtigungen.

Wenn Sie prüfen möchten, ob der Nutzer Ihrer Anwendung Zugriff auf einen bestimmten Bereich gewährt hat, sehen Sie sich das Feld scope in der Antwort des Zugriffstokens an. Die Zugriffsbereiche, die durch das Zugriffstoken gewährt werden, ausgedrückt als Liste von durch Leerzeichen getrennten Strings, bei denen die Groß-/Kleinschreibung beachtet wird.

Die folgende Beispielantwort für ein Zugriffstoken zeigt beispielsweise, dass der Nutzer Ihrer Anwendung die Berechtigung erteilt hat, seine YouTube-Videos, -Bewertungen, -Kommentare und -Untertitel anzusehen, zu bearbeiten und dauerhaft zu löschen:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Google APIs aufrufen

Nachdem Ihre Anwendung ein Zugriffstoken erhalten hat, können Sie damit im Namen eines bestimmten Nutzerkontos Aufrufe an eine Google API senden, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein, indem Sie entweder einen access_token-Suchparameter oder einen Authorization-HTTP-Header-Bearer-Wert angeben. Wenn möglich, ist der HTTP-Header vorzuziehen, da Abfragestrings in Server-Logs sichtbar sein können. In den meisten Fällen können Sie eine Clientbibliothek verwenden, um Ihre Aufrufe an Google APIs einzurichten (z. B. beim Aufrufen der YouTube Data API).

Die YouTube Data API unterstützt Dienstkonten nur für YouTube-Rechteinhaber, die mehrere YouTube-Kanäle besitzen und verwalten, z. B. Musiklabels und Filmstudios.

Sie können alle Google APIs ausprobieren und ihre Bereiche im OAuth 2.0 Playground ansehen.

HTTP-GET-Beispiele

Ein Aufruf des Endpunkts youtube.channels (YouTube Data API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen: Beachten Sie, dass Sie Ihr eigenes Zugriffstoken angeben müssen:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Hier ist ein Aufruf derselben API für den authentifizierten Nutzer mit dem Abfragestringparameter access_token:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Beispiele für curl

Sie können diese Befehle mit der curl-Befehlszeilenanwendung testen. Hier ein Beispiel, in dem die HTTP-Header-Option (bevorzugt) verwendet wird:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Oder alternativ die Option für den Abfragestringparameter:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Zugriffstoken aktualisieren

Zugriffstokens laufen regelmäßig ab und werden zu ungültigen Anmeldedaten für eine zugehörige API-Anfrage. Sie können ein Zugriffstoken aktualisieren, ohne den Nutzer um Erlaubnis zu bitten (auch wenn der Nutzer nicht anwesend ist), wenn Sie Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.

Wenn Sie ein Zugriffstoken aktualisieren möchten, sendet Ihre Anwendung eine HTTPS-POST-Anfrage an den Autorisierungsserver von Google (https://oauth2.googleapis.com/token). Diese Anfrage enthält die folgenden Parameter im Anfragetext:

Die Verwendung von DPoP ist optional, wird aber für mehr Sicherheit empfohlen. Wenn Sie DPoP mit einem Aktualisierungstoken verwenden möchten, muss Ihre Anwendung für jede Anfrage an den Token-Endpunkt ein neues, eindeutiges DPoP-Proof-JWT generieren. Dieser Nachweis muss mit demselben privaten Schlüssel signiert werden, der beim ersten Austausch des Autorisierungscodes verwendet wurde. Ihre Anwendung fügt den Nachweis als HTTP-Anfrageheader hinzu.

Das folgende Snippet zeigt eine Beispielanfrage:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: DPOP_PROOF_JWT

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

Wenn Sie DPoP mit einem Aktualisierungstoken verwenden möchten, müssen Sie für die Anfrage ein neues, eindeutiges DPoP-Proof-JWT generieren. Eine detaillierte Anleitung zum Generieren des Schlüsselpaars und zum Erstellen des JWT finden Sie unter DPoP-Proof erstellen.

Ein erfolgreicher Austausch wird durch eine 200 OK-Antwort mit einem neuen Zugriffstoken angezeigt. Wenn DPoP verwendet wird, ist der token_type Bearer. Eine erfolgreiche Antwort bestätigt, dass der DPoP-Proof für das Aktualisierungstoken akzeptiert wurde. Google kann in der Antwort auch einen neuen HTTP-Header DPoP-Nonce zurückgeben. Wenn er zurückgegeben wird, muss Ihr Client diese Nonce im Cache speichern und sie in nachfolgenden Anfragen in den nonce-Claim des DPoP-Proofs aufnehmen.

Ein fehlgeschlagener Austausch tritt auf, wenn der DPoP-Header fehlt, ungültig ist oder einen falschen Schlüssel verwendet. Weitere Informationen zu bestimmten DPoP-Fehlercodes und zur Verarbeitung von Nonces finden Sie unter Fehlgeschlagener Austausch.

Das folgende Snippet zeigt ein Beispiel für erfolgreiche Antwortheader und einen Antworttext, wenn DPoP verwendet wird:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Beachten Sie, dass die Anzahl der ausgestellten Aktualisierungstokens begrenzt ist. Es gibt ein Limit pro Client/Nutzer-Kombination und ein weiteres pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens im Langzeitspeicher speichern und sie so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, kann es sein, dass diese Limits erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Token-Widerruf

In einigen Fällen möchte ein Nutzer möglicherweise den Zugriff einer Anwendung widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen finden Sie im Supportdokument Drittanbieter-Websites und ‑Apps mit Zugriff auf Ihr Konto im Abschnitt „Zugriff von Websites oder Apps entfernen“.

Eine Anwendung kann den ihr gewährten Zugriff auch programmatisch widerrufen. Der programmatische Widerruf ist wichtig, wenn ein Nutzer ein Abo kündigt, eine Anwendung entfernt oder sich die von einer App benötigten API-Ressourcen erheblich geändert haben. Das bedeutet, dass ein Teil des Entfernungsprozesses eine API-Anfrage sein kann, um sicherzustellen, dass die der Anwendung zuvor gewährten Berechtigungen entfernt werden.

Wenn Sie ein Token programmatisch widerrufen möchten, stellt Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke und fügt das Token als Parameter ein:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Das Token kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn das Token ein Zugriffstoken ist und ein entsprechendes Aktualisierungstoken hat, wird das Aktualisierungstoken ebenfalls widerrufen.

Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der HTTP-Statuscode der Antwort 200. Bei Fehlerbedingungen wird ein HTTP-Statuscode 400 zusammen mit einem Fehlercode zurückgegeben.

Methoden zur Weiterleitung in die App

Apps schützen

Zeitbasierter Zugriff

Mit dem zeitbasierten Zugriff kann ein Nutzer Ihrer App für eine begrenzte Dauer Zugriff auf seine Daten gewähren, um eine Aktion auszuführen. In ausgewählten Google-Produkten ist während des Einwilligungsverfahrens ein zeitbasierter Zugriff verfügbar. Nutzer können damit den Zugriff für einen begrenzten Zeitraum gewähren. Ein Beispiel ist die Data Portability API, die eine einmalige Übertragung von Daten ermöglicht.

Wenn ein Nutzer Ihrer Anwendung zeitbasierten Zugriff gewährt, läuft das Aktualisierungstoken nach der angegebenen Dauer ab. Beachten Sie, dass Aktualisierungstokens unter bestimmten Umständen früher ungültig werden können. Weitere Informationen finden Sie in diesen Fällen. Das Feld refresh_token_expires_in, das in der Antwort auf den Austausch des Autorisierungscodes zurückgegeben wird, stellt in solchen Fällen die verbleibende Zeit bis zum Ablauf des Aktualisierungstokens dar.

Weiterführende Literatur

In der IETF Best Current Practice OAuth 2.0 for Native Apps werden viele der hier dokumentierten Best Practices beschrieben.