OAuth 2.0 für mobile Apps; Desktop-Apps

. In der Übersicht werden die von Google unterstützten OAuth 2.0-Abläufe zusammengefasst. So könnt ihr prüfen, ob ihr den richtigen Ablauf für eure Anwendung ausgewählt habt.

In diesem Dokument wird erläutert, wie Anwendungen auf Geräten wie Smartphones, Tablets und Computern die OAuth 2.0-Endpunkte von Google verwenden, um den Zugriff auf Google APIs zu autorisieren.

Mit OAuth 2.0 können Nutzer bestimmte Daten für eine Anwendung freigeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Beispielsweise kann eine Anwendung OAuth 2.0 verwenden, um die Berechtigung von Nutzern zum Speichern von Dateien in Google Drive zu erhalten.

Installierte Anwendungen werden auf einzelne Geräte verteilt und es wird davon ausgegangen, dass diese Anwendungen keine Secrets speichern können. Sie können auf Google APIs zugreifen, während der Nutzer in der App anwesend oder im Hintergrund ist.

Dieser Autorisierungsvorgang ähnelt dem für Webserveranwendungen. Der Hauptunterschied besteht darin, dass installierte Apps den Systembrowser öffnen und einen lokalen Weiterleitungs-URI angeben müssen, um Antworten des Google-Autorisierungsservers zu verarbeiten.

Alternativen

Für mobile Apps kannst du Google Log-in für Android oder iOS verwenden. Die Google Log-in-Clientbibliotheken verarbeiten die Authentifizierung und die Nutzerautorisierung und sind möglicherweise einfacher zu implementieren als das hier beschriebene untergeordnete Protokoll.

Informationen zu Apps auf Geräten, die keinen Systembrowser unterstützen oder die nur über eingeschränkte Eingabefunktionen verfügen, wie Fernseher, Spielekonsolen, Kameras oder Drucker, findest du unter OAuth 2.0 für Fernseher und Geräte oder Anmeldung auf Fernsehern und Geräten mit eingeschränkter Eingabe.

Bibliotheken und Beispiele

Wir empfehlen die folgenden Bibliotheken und Beispiele, um den in diesem Dokument beschriebenen OAuth 2.0-Vorgang zu implementieren:

Voraussetzungen

Die APIs für Ihr Projekt aktivieren

Jede Anwendung, die Google APIs aufruft, muss diese APIs in der API Consoleaktivieren.

So aktivieren Sie eine API für Ihr Projekt:

  1. Open the API Library im Google API Console.
  2. If prompted, select a project, or create a new one.
  3. In der API Library sind alle verfügbaren APIs nach Produktfamilie und Beliebtheit gruppiert. Wenn die API, die Sie aktivieren möchten, nicht in der Liste angezeigt wird, können Sie danach suchen oder sie in der entsprechenden Produktfamilie auf Alle ansehen klicken.
  4. Wählen Sie die API aus, die Sie aktivieren möchten, und klicken Sie dann auf die Schaltfläche Aktivieren.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Anmeldedaten für die Autorisierung erstellen

Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, muss Anmeldedaten für die Autorisierung der Anwendung für den OAuth 2.0-Server von Google haben. In den folgenden Schritten wird erläutert, 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. Go to the Credentials page.
  2. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
  3. In den folgenden Abschnitten werden die Clienttypen und die Weiterleitungsmethoden beschrieben, die vom Google-Autorisierungsserver unterstützt werden. Wählen Sie den für Ihre Anwendung empfohlenen Clienttyp aus, benennen Sie den OAuth-Client und legen Sie die anderen Felder im Formular entsprechend fest.

Benutzerdefiniertes URI-Schema (Android, iOS, UWP)

Ein benutzerdefiniertes URI-Schema wird für Android-Apps, iOS-Apps und UWP-Apps (Universal Windows Platform) empfohlen.

Android
  1. Wählen Sie den Anwendungstyp Android aus.
  2. Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird im Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
  3. Geben Sie den Paketnamen Ihrer Android-App ein. Dieser Wert ist im Attribut package des Elements <manifest> in der App-Manifestdatei definiert.
  4. Geben Sie den SHA1-Signaturzertifikat-Fingerabdruck der App-Bereitstellung ein.
    • Wenn deine App die App-Signatur von Google Play verwendet, kopiere den SHA-1-Fingerabdruck von der App-Signaturseite der Play Console.
    • Wenn Sie Ihren eigenen Schlüsselspeicher und Signaturschlüssel verwalten, verwenden Sie das in Java enthaltene Dienstprogramm keytool, um Zertifikatsinformationen in einem für Menschen lesbaren Format zu drucken. Kopieren Sie den Wert SHA1 im Abschnitt Certificate fingerprints der keytool-Ausgabe. Weitere Informationen finden Sie unter Client authentifizieren in der Dokumentation zu Google APIs für Android.
  5. Klicken Sie auf Erstellen.
iOS
  1. Wählen Sie den Anwendungstyp iOS aus.
  2. Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird im Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
  3. Geben Sie die Bundle-ID für Ihre App ein. Die Bundle-ID ist der Wert des CFBundleIdentifier-Schlüssels in der Ressourcenliste für die Informationseigenschaft Ihrer App (info.plist). Der Wert wird am häufigsten im Bereich „Allgemein“ oder im Bereich „Signatur und Funktionen“ des Xcode-Projekteditors angezeigt. Die Bundle-ID wird auch auf der App Store-Website von Apple im Abschnitt „Allgemeine Informationen“ der Seite „App-Informationen“ für die App angezeigt.
  4. (Optional)

    Geben Sie die App Store-ID Ihrer App ein, wenn die App im App Store von Apple veröffentlicht wurde. Die Store-ID ist ein numerischer String, der in jeder Apple App Store-URL enthalten ist.

    1. Öffne die Apple App Store App auf deinem iOS- oder iPadOS-Gerät.
    2. Suchen Sie nach Ihrer App.
    3. Klicken Sie auf die Schaltfläche „Teilen“ (quadratisch und Pfeil nach oben).
    4. Wählen Sie Link kopieren aus.
    5. Fügen Sie den Link in einen Texteditor ein. Die App Store-ID ist der letzte Teil der URL.

      Beispiel: https://apps.apple.com/app/google/id284815942

  5. (Optional)

    Geben Sie Ihre Team-ID ein. Weitere Informationen findest du in der Dokumentation deines Apple-Entwicklerkontos unter Team-ID ermitteln.

  6. Klicken Sie auf Erstellen.
UWP
  1. Wählen Sie den Anwendungstyp Universelle Windows-Plattform aus.
  2. Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird im Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
  3. Geben Sie die 12-stellige Microsoft Store-ID Ihrer App ein. Sie finden diesen Wert im Microsoft-Partnercenter auf der Seite App-Identität im Abschnitt „App-Verwaltung“.
  4. Klicken Sie auf Erstellen.

Bei UWP-Apps darf das benutzerdefinierte URI-Schema nicht länger als 39 Zeichen sein.

Loopback-IP-Adresse (macOS, Linux, Windows-Desktop)

Damit der Autorisierungscode mit dieser URL empfangen wird, muss Ihre Anwendung den lokalen Webserver beobachten. Das ist auf vielen, aber nicht auf allen Plattformen möglich. Wenn deine Plattform dies jedoch unterstützt, ist dies die empfohlene Methode zum Abrufen des Autorisierungscodes.

Wenn deine App die Autorisierungsantwort erhält, sollte sie für die Nutzerfreundlichkeit eine HTML-Seite anzeigen, die den Nutzer auffordert, den Browser zu schließen und zu deiner App zurückzukehren.

Empfohlene Verwendung macOS-, Linux- und Windows-Desktop-Apps (jedoch nicht die universelle Windows-Plattform)
Formularwerte Wählen Sie als Anwendungstyp Desktop-App aus.

Manuelles Kopieren/Einfügen

Zugriffsbereiche identifizieren

Bereiche ermöglichen es Ihrer Anwendung, nur den erforderlichen Zugriff auf die Ressourcen anzufordern, während Nutzer auch steuern können, wie viel Zugriff sie der Anwendung gewähren. Daher besteht möglicherweise eine inverse Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche identifizieren, auf die Ihre App Zugriff benötigt.

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-Zugriffstoken abrufen

Die folgenden Schritte zeigen, 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 haben, bevor sie eine Google API-Anfrage ausführen kann, die eine Nutzerautorisierung erfordert.

Schritt 1: Codeprüfung und Identitätsbestätigung generieren

Google unterstützt das Protokoll Proof Key for Code Exchange (Proof Key for Code Exchange), um die installierte Anwendung sicherer zu machen. Für jede Autorisierungsanfrage wird ein eindeutiger Codeprüfer erstellt. Der transformierte Wert „code_challenge“ wird an den Autorisierungsserver gesendet, um den Autorisierungscode abzurufen.

Codeprüfer erstellen

code_verifier ist ein kryptografischer zufälliger String mit hoher Entropie unter Verwendung der nicht reservierten Zeichen [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" mit einer Mindestlänge von 43 Zeichen und einer maximalen Länge von 128 Zeichen.

Die Code-Überprüfung sollte genügend Entropie haben, damit der Wert nicht erraten werden kann.

Code-Challenge erstellen

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

Methoden zum Generieren von Code-Herausforderungen
S256 (empfohlen) Die Code-Herausforderung ist der Base64-URL-Code (ohne Auffüllung) mit dem SHA256-Hash-Wert der Codeprüffunktion.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
einfach Die Code-Herausforderung hat denselben Wert wie die oben erstellte Code-Prüfer.
code_challenge = code_verifier

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

Senden Sie zum Abrufen der Nutzerautorisierung eine Anfrage an den Autorisierungsserver von Google unter https://accounts.google.com/o/oauth2/v2/auth. Dieser Endpunkt übernimmt die aktive Sitzungssuche, authentifiziert den Nutzer und erhält die Nutzereinwilligung. Der Endpunkt ist nur über SSL zugänglich und verweigert HTTP-Verbindungen (nicht SSL-Verbindungen).

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

Parameter
client_id Erforderlich

Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in API Console Credentials page.

redirect_uri Erforderlich

Legt fest, wie der Autorisierungsserver von Google eine Antwort an Ihre Anwendung sendet. Es gibt verschiedene Weiterleitungsoptionen für installierte Anwendungen und Sie haben Ihre Autorisierungsdaten im Hinblick auf eine bestimmte Weiterleitungsmethode eingerichtet.

Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in API Console Credentials pageIhres Clients konfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, wird der Fehler redirect_uri_mismatch angezeigt.

In der folgenden Tabelle sehen Sie den entsprechenden redirect_uri-Parameterwert für jede Methode:

redirect_uri-Werte
Benutzerdefiniertes URI-Schema com.example.app:redirect_uri_path

oder

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app ist die umgekehrte DNS-Notation einer Domain, die unter Ihrer Kontrolle steht. Das benutzerdefinierte Schema muss einen Punkt enthalten, um gültig zu sein.
  • com.googleusercontent.apps.123 ist die umgekehrte DNS-Notation der Client-ID.
  • redirect_uri_path ist eine optionale Pfadkomponente, z. B. /oauth2redirect. Der Pfad muss mit einem einzelnen Schrägstrich beginnen, der sich von regulären HTTP-URLs unterscheidet.
Loopback-IP-Adresse http://127.0.0.1:port oder http://[::1]:port

Fragen Sie Ihre Plattform nach der relevanten Loopback-IP-Adresse ab und starten Sie einen HTTP-Listener an einem zufällig verfügbaren Port. Ersetzen Sie port durch die tatsächliche Portnummer, die Ihre Anwendung überwacht.

Beachten Sie, dass die Unterstützung für die Weiterleitungsoption „Loopback-IP-Adresse“ in mobilen Apps eingestellt ist.

response_type Erforderlich

Legt fest, ob der Google OAuth 2.0-Endpunkt einen Autorisierungscode zurückgibt.

Legen Sie den Parameterwert für installierte Anwendungen auf code fest.

scope Erforderlich

Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte bilden die Grundlage für den Zustimmungsbildschirm, den Google dem Nutzer anzeigt.

Mit Bereichen kann Ihre Anwendung nur den Zugriff auf die erforderlichen Ressourcen anfordern und Nutzer können auch steuern, welche Zugriffsrechte sie Ihrer Anwendung gewähren. Daher besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen.

code_challenge Empfohlen

Gibt eine codierte code_verifier an, die während des Autorisierungscodeaustauschs als serverseitige Identitätsbestätigung verwendet wird. Weitere Informationen finden Sie oben im Abschnitt Abfrage zur Codeerstellung.

code_challenge_method Empfohlen

Gibt an, welche Methode zum Codieren einer code_verifier verwendet wurde, die beim Austausch von Autorisierungscodes verwendet wird. Dieser Parameter muss mit dem oben beschriebenen Parameter code_challenge verwendet werden. Der Wert von code_challenge_method ist standardmäßig auf plain gesetzt, wenn er nicht in der Anfrage enthalten ist und code_challenge enthält. Die einzigen unterstützten Werte für diesen Parameter sind S256 oder plain.

state Empfohlen

Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechtzuerhalten. Der Server gibt den genauen Wert zurück, den Sie als name=value-Paar in der URL-Fragment-ID (#) der redirect_uri senden, nachdem der Nutzer der Zugriffsanfrage Ihrer Anwendung zugestimmt oder sie abgelehnt hat.

Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung zu leiten, Nonces zu senden und eine websiteübergreifende Anfragefälschung zu verringern. Da Ihre redirect_uri erraten werden kann, können Sie mit einem state-Wert die Sicherheit erhöhen, dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanfrage ist. Wenn Sie einen zufälligen String generieren oder den Hash eines Cookies oder eines anderen Werts codieren, der den Clientstatus erfasst, können Sie die Antwort validieren. Damit stellen Sie außerdem sicher, dass die Anfrage und die Antwort vom selben Browser stammen, um Sie vor Angriffen wie der websiteübergreifenden Anfragefälschung zu schützen. Ein Beispiel für das Erstellen und Bestätigen eines state-Tokens finden Sie in der Dokumentation zu OpenID Connect.

login_hint Optional

Wenn die Anwendung weiß, welcher Nutzer sich authentifizieren möchte, kann sie mit diesem Parameter einen Hinweis für den Google-Authentifizierungsserver bereitstellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen. Dazu füllt er entweder das E-Mail-Feld im Anmeldeformular aus oder wählt die entsprechende Mehrfachanmeldung aus.

Legen Sie den Parameterwert auf eine E-Mail-Adresse oder eine sub-Kennung fest, die der Google-ID des Nutzers entspricht.

Beispiele für Autorisierungs-URLs

Auf den Tabs unten sehen Sie Beispiele für Autorisierungs-URLs der verschiedenen Weiterleitungs-URI-Optionen.

Die URLs sind bis auf den Wert des Parameters redirect_uri identisch. Die URLs enthalten außerdem die erforderlichen Parameter response_type und client_id sowie den optionalen Parameter state. Jede URL enthält Zeilenumbrüche und Leerzeichen zur besseren Lesbarkeit.

Benutzerdefiniertes URI-Schema

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 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

Loopback-IP-Adresse

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 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 zur Einwilligung auf

In diesem Schritt entscheidet der Nutzer, ob er Ihrer Anwendung den angeforderten Zugriff gewähren soll. In dieser Phase zeigt Google ein Einwilligungsfenster mit dem Namen Ihrer Anwendung und den Google API-Diensten an, auf die mit den Autorisierungsanmeldedaten des Nutzers eine Zugriffsberechtigung angefordert wird, sowie eine Zusammenfassung der zu gewährenden Zugriffsbereiche. Der Nutzer kann dann zustimmen, um Zugriff auf einen oder mehrere Bereiche zu gewähren, die von Ihrer Anwendung angefordert werden, oder die Anfrage abzulehnen.

Ihre Anwendung muss zu diesem Zeitpunkt nichts tun, da sie auf die Antwort des OAuth 2.0-Servers von Google wartet, der angibt, ob ein Zugriff gewährt wurde. Diese Antwort wird im folgenden Schritt erläutert.

Fehler

Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google können anstelle der erwarteten Authentifizierungs- und Autorisierungsabläufe Fehlermeldungen für Nutzer anzeigen. Die häufigsten Fehlercodes und Lösungsvorschläge sind unten aufgeführt.

admin_policy_enforced

Das Google-Konto kann einen oder mehrere Bereiche nicht autorisieren, die aufgrund der Richtlinien seines Google Workspace-Administrators angefordert wurden. Im Hilfeartikel Zugriff externer und interner Apps auf Google Workspace-Daten verwalten finden Sie weitere Informationen dazu, wie Administratoren den Zugriff auf alle oder sensible und eingeschränkte Bereiche einschränken können, bis der OAuth-Client-ID explizit Zugriff gewährt wird.

disallowed_useragent

Der Autorisierungsendpunkt wird in einem eingebetteten User-Agent angezeigt, der gemäß den OAuth 2.0-Richtlinien von Google unzulässig ist.

Android

Diese Fehlermeldung kann unter Android-Entwicklern angezeigt werden, wenn Autorisierungsanfragen in android.webkit.WebView geöffnet werden. Entwickler sollten stattdessen Android-Bibliotheken wie Google Log-in für Android oder AppAuth für Android der OpenID Foundation verwenden.

Webentwickler können diesen Fehler erhalten, wenn eine Android-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von deiner Website zum OAuth 2.0-Autorisierungsendpunkt von Google wechselt. Entwickler sollten das Öffnen allgemeiner Links im Standard-Link-Handler des Betriebssystems zulassen, der sowohl Handler für Android-App-Links als auch die Standard-Browser-App enthält. Die Bibliothek Benutzerdefinierte Android-Tabs ist ebenfalls eine unterstützte Option.

iOS

iOS- und macOS-Entwickler erhalten möglicherweise diesen Fehler, wenn Autorisierungsanfragen in WKWebView geöffnet werden. Entwickler sollten stattdessen iOS-Bibliotheken wie Google Log-in für iOS oder AppAuth für iOS der OpenID Foundation verwenden.

Dieser Fehler kann auftreten, wenn eine iOS- oder macOS-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von deiner Website zum OAuth 2.0-Autorisierungsendpunkt von Google wechselt. Entwickler sollten das Öffnen allgemeiner Links im Standard-Link-Handler des Betriebssystems zulassen, das sowohl Handler für universelle Links als auch die Standard-Browser-App umfasst. Die Bibliothek SFSafariViewController wird ebenfalls unterstützt.

org_internal

Die OAuth-Client-ID in der Anfrage ist Teil eines Projekts, das den Zugriff auf Google-Konten in einer bestimmten Google Cloud-Organisation beschränkt. Weitere Informationen zu dieser Konfigurationsoption finden Sie im Hilfeartikel OAuth-Zustimmungsbildschirm einrichten.

invalid_grant

Wenn du eine Codeprüfung und die Identitätsbestätigung verwendest, ist der Parameter code_callenge ungültig oder fehlt. Der Parameter code_challenge muss richtig festgelegt sein.

Beim Aktualisieren eines Zugriffstokens ist das Token möglicherweise abgelaufen oder ungültig. Authentifizieren Sie den Nutzer noch einmal und bitten Sie ihn um Zustimmung, um neue Tokens zu erhalten. Wenn dieser Fehler weiterhin auftritt, prüfen Sie, ob Ihre Anwendung korrekt konfiguriert wurde und ob Sie die richtigen Tokens und Parameter in Ihrer Anfrage verwenden. Andernfalls wurde das Nutzerkonto möglicherweise gelöscht oder deaktiviert.

redirect_uri_mismatch

Der in der Autorisierungsanfrage übergebene redirect_uri stimmt nicht mit einem autorisierten Weiterleitungs-URI für die OAuth-Client-ID überein. Prüfen Sie autorisierte Weiterleitungs-URIs in Google API Console Credentials page.

Die übergebene redirect_uri ist möglicherweise für den Clienttyp ungültig.

Der Parameter redirect_uri kann sich auf den OAuth-Out-of-Band-Vorgang (OOB) beziehen, der verworfen wurde und nicht mehr unterstützt wird. Informationen zum Einbinden der Integration finden Sie im Migrationsleitfaden.

Schritt 4: OAuth 2.0-Serverantwort verarbeiten

Die Art und Weise, wie Ihre Anwendung die Autorisierungsantwort empfängt, hängt vom verwendeten Weiterleitungs-URI-Schema ab. Unabhängig vom Schema enthält die Antwort entweder einen Autorisierungscode (code) oder einen Fehler (error). Zum Beispiel bedeutet error=access_denied, dass der Nutzer die Anfrage abgelehnt hat.

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

Schritt 5: Autorisierungscode für Aktualisierungs- und Zugriffstokens austauschen

Um einen Autorisierungscode gegen ein Zugriffstoken auszutauschen, rufen Sie den Endpunkt https://oauth2.googleapis.com/token auf und legen die folgenden Parameter fest:

Felder
client_id Die Client-ID, die von API Console Credentials pageerhalten wurde.
client_secret Der Clientschlüssel, der von API Console Credentials pageerhalten wurde.
code Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wurde.
code_verifier Die Codeprüffunktion, die Sie in Schritt 1 erstellt haben.
grant_type Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Feldes auf authorization_code festgelegt werden.
redirect_uri Einer der Weiterleitungs-URIs, die für Ihr Projekt in der API Console Credentials page für die angegebene client_id aufgeführt sind.

Das folgende Snippet zeigt eine Beispielanfrage:

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

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

Google antwortet auf diese Anfrage, indem es ein JSON-Objekt mit einem kurzlebigen Zugriffstoken und einem Aktualisierungstoken zurückgibt.

Die Antwort umfasst die folgenden Felder:

Felder
access_token Das Token, das Ihre Anwendung zum Autorisieren einer Google API-Anfrage sendet.
expires_in Die verbleibende Lebensdauer des Zugriffstokens in Sekunden.
id_token Hinweis:Dieses Attribut wird nur zurückgegeben, wenn Ihre Anfrage einen Identitätsbereich wie openid, profile oder email enthält. Der Wert ist ein JSON-Webtoken (JWT), das digital signierte Identitätsinformationen über den Nutzer enthält.
refresh_token Ein Token, mit dem Sie ein neues Zugriffstoken abrufen können. Aktualisierungstokens sind gültig, bis der Nutzer den Zugriff widerruft. Für installierte Anwendungen werden immer Aktualisierungstokens zurückgegeben.
scope Der von access_token gewährte Zugriffsbereich, ausgedrückt als Liste von Strings, bei denen die Leerzeichen durch Leerzeichen getrennt sind.
token_type Der Typ des zurückgegebenen Tokens. Derzeit ist der Wert dieses Felds immer auf Bearer festgelegt.

Das folgende Snippet zeigt eine Beispielantwort:

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

Google APIs aufrufen

Nachdem Ihre Anwendung ein Zugriffstoken erhalten hat, können Sie mit dem Token im Namen eines Nutzerkontos eine Google API aufrufen, wenn der Zugriffsbereich, der für die API erforderlich ist, gewährt wurde. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein, indem Sie entweder einen access_token-Abfrageparameter oder einen Authorization-HTTP-Header-Bearer-Wert einbinden. Wenn möglich, ist der HTTP-Header zu bevorzugen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen können Sie eine Clientbibliothek verwenden, um Aufrufe an Google APIs einzurichten (z. B. beim Aufruf der Drive Files API).

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

Beispiele für HTTP GET

Ein Aufruf des Endpunkts drive.files (Drive File API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen. Sie müssen ein eigenes Zugriffstoken angeben:

GET /drive/v2/files 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/drive/v2/files?access_token=access_token

Beispiele für curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Oder die Option für den Abfragestringparameter:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Zugriffstokens aktualisieren

Zugriffstoken laufen in regelmäßigen Abständen ab und werden zu ungültigen Anmeldedaten für eine ähnliche API-Anfrage. Sie können ein Zugriffstoken aktualisieren, ohne den Nutzer um seine Berechtigung zu bitten (auch wenn er nicht anwesend ist), wenn Sie Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.

Zum Aktualisieren eines Zugriffstokens sendet die Anwendung eine HTTPS-POST-Anfrage an den Google-Autorisierungsserver (https://oauth2.googleapis.com/token), der die folgenden Parameter enthält:

Felder
client_id Die von API Consoleabgerufene Client-ID.
client_secret Der Clientschlüssel, der von API Consoleabgerufen wird. (client_secret gilt nicht für Anfragen von Clients, die als Android-, iOS- oder Chrome-Anwendungen registriert sind.)
grant_type Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Feldes auf refresh_token festgelegt werden.
refresh_token Das vom Autorisierungscode-Austausch zurückgegebene Aktualisierungstoken.

Das folgende Snippet zeigt eine Beispielanfrage:

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Solange der Nutzer der Anwendung keinen Zugriff entzogen hat, gibt der Tokenserver ein JSON-Objekt zurück, das ein neues Zugriffstoken enthält. Das folgende Snippet zeigt eine Beispielantwort:

{
  "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: ein Limit pro Client/Nutzer-Kombination und ein anderes pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens im Langzeitspeicher speichern und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Token widerrufen

In manchen Fällen möchte ein Nutzer den Zugriff auf eine Anwendung widerrufen. Ein Nutzer kann den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen findest du im Supportdokument unter Websites oder Apps mit Zugriff auf dein Konto entfernen.

Eine Anwendung kann auch den Zugriff, der ihr gewährt wurde, programmatisch widerrufen. Der programmatische Widerruf ist in Fällen wichtig, in denen ein Nutzer sich abmeldet, eine Anwendung entfernt oder die für eine Anwendung erforderlichen API-Ressourcen sich erheblich geändert haben. Mit anderen Worten: Ein Teil des Entfernungsprozesses kann eine API-Anfrage umfassen, mit der die zuvor für die Anwendung gewährten Berechtigungen entfernt werden.

Wenn Sie ein Token programmatisch widerrufen möchten, sendet 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 dieses ebenfalls widerrufen.

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

Weiterführende Literatur

Viele der hier aufgeführten Best Practices werden im IETF Best Current Practice OAuth 2.0 for Native Apps beschrieben.