OAuth 2.0 für mobile und Desktop-Apps

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

OAuth 2.0 ermöglicht es Benutzern, bestimmte Daten mit einer Anwendung zu teilen, während ihre Benutzernamen, Passwörter und andere Informationen privat bleiben. Beispielsweise kann eine Anwendung OAuth 2.0 verwenden, um die Erlaubnis von Benutzern zu erhalten, Dateien in ihren Google Drives zu speichern.

Installierte Apps werden auf einzelne Geräte verteilt, und es wird davon ausgegangen, dass diese Apps keine Geheimnisse bewahren können. Sie können auf Google-APIs zugreifen, während der Benutzer in der App anwesend ist oder wenn die App im Hintergrund ausgeführt wird.

Dieser Autorisierungsablauf ähnelt dem für Webserveranwendungen verwendeten . Der Hauptunterschied besteht darin, dass installierte Apps den Systembrowser öffnen und einen lokalen Umleitungs-URI bereitstellen müssen, um Antworten vom Autorisierungsserver von Google zu verarbeiten.

Alternativen

Für mobile Apps bevorzugen Sie möglicherweise die Google-Anmeldung für Android oder iOS . Die Google Sign-in-Clientbibliotheken verarbeiten die Authentifizierung und Benutzerautorisierung und sind möglicherweise einfacher zu implementieren als das hier beschriebene untergeordnete Protokoll.

Informationen zu Apps, die auf Geräten ausgeführt werden, die keinen Systembrowser unterstützen oder die eingeschränkte Eingabemöglichkeiten haben, wie z. B. Fernseher, Spielkonsolen, Kameras oder Drucker, finden Sie unter OAuth 2.0 für Fernseher und Geräte oder Anmeldung auf Fernsehern und eingeschränkten Eingabegeräten .

Bibliotheken und Proben

Wir empfehlen die folgenden Bibliotheken und Beispiele, um Ihnen bei der Implementierung des in diesem Dokument beschriebenen OAuth 2.0-Flows zu helfen:

Voraussetzungen

Aktivieren Sie APIs für Ihr Projekt

Jede Anwendung, die Google-APIs aufruft, muss diese APIs im 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. Der API Library listet alle verfügbaren APIs auf, gruppiert nach Produktfamilie und Beliebtheit. Wenn die API, die Sie aktivieren möchten, nicht in der Liste angezeigt wird, verwenden Sie die Suche, um sie zu finden, oder klicken Sie in der Produktfamilie, zu der sie gehört, auf Alle anzeigen.
  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.

Autorisierungsdaten erstellen

Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google-APIs verwendet, muss über Autorisierungsdaten verfügen, die die Anwendung gegenüber dem OAuth 2.0-Server von Google identifizieren. In den folgenden Schritten wird erläutert, wie Sie Anmeldeinformationen für Ihr Projekt erstellen. Ihre Anwendungen können dann die Anmeldeinformationen verwenden, um auf APIs zuzugreifen, 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 der Autorisierungsserver von Google unterstützt. Wählen Sie den für Ihre Anwendung empfohlenen Client-Typ, benennen Sie Ihren 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 Apps für die universelle Windows-Plattform (UWP) empfohlen.

Android
  1. Wählen Sie den Android -Anwendungstyp aus.
  2. Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird auf dem Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
  3. Geben Sie den Paketnamen Ihrer Android-App ein. Dieser Wert ist impackage des <manifest> -Elements in Ihrer App-Manifestdatei definiert.
  4. Geben Sie den Fingerabdruck des SHA-1-Signaturzertifikats der App-Verteilung ein.
    • Wenn Ihre App die App-Signatur von Google Play verwendet, kopieren Sie 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 SHA1 -Wert in den Abschnitt „ Certificate fingerprints “ der keytool- Ausgabe. Weitere Informationen finden Sie unter Authentifizierung Ihres Clients in der Dokumentation zu Google APIs für Android.
  5. Klicken Sie auf Erstellen .
iOS
  1. Wählen Sie den iOS -Anwendungstyp aus.
  2. Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird auf dem Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
  3. Geben Sie die Bundle-ID für Ihre App ein. Die Paket-ID ist der Wert des Schlüssels CFBundleIdentifier in der Ressourcendatei der Informationseigenschaftsliste Ihrer App ( info.plist ). Der Wert wird am häufigsten im Bereich „Allgemein“ oder im Bereich „Signaturen und Funktionen“ des Xcode-Projekteditors angezeigt. Die Paket-ID wird auch im Abschnitt „Allgemeine Informationen“ der Seite „App-Informationen“ für die App auf der App Store Connect-Website von Apple angezeigt.
  4. (Optional)

    Geben Sie die App Store-ID Ihrer App ein, wenn die App im App Store von Apple veröffentlicht ist. Die Store-ID ist eine numerische Zeichenfolge, die in jeder Apple App Store-URL enthalten ist.

    1. Öffnen Sie die Apple App Store App auf Ihrem iOS- oder iPadOS-Gerät.
    2. Suchen Sie nach Ihrer Anwendung.
    3. Wählen Sie die Teilen-Schaltfläche (Quadrat und Pfeil-nach-oben-Symbol).
    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/id 284815942

  5. (Optional)

    Geben Sie Ihre Team-ID ein. Weitere Informationen finden Sie unter Lokalisieren Ihrer Team-ID in der Dokumentation zum Apple-Entwicklerkonto.

  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 auf dem 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 Partner Center auf der Seite App-Identität im Abschnitt App-Verwaltung.
  4. Klicken Sie auf Erstellen .

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

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

Um den Autorisierungscode über diese URL zu erhalten, muss Ihre Anwendung den lokalen Webserver überwachen. Das ist auf vielen, aber nicht allen Plattformen möglich. Wenn Ihre Plattform dies jedoch unterstützt, ist dies der empfohlene Mechanismus zum Abrufen des Autorisierungscodes.

Wenn Ihre App die Autorisierungsantwort erhält, sollte sie für eine optimale Benutzerfreundlichkeit antworten, indem sie eine HTML-Seite anzeigt, die den Benutzer anweist, den Browser zu schließen und zu Ihrer App zurückzukehren.

Empfohlene Verwendung macOS-, Linux- und Windows-Desktop-Apps (aber nicht die universelle Windows-Plattform).
Werte bilden Legen Sie den Anwendungstyp auf Desktop-App fest .

Manuelles Kopieren/Einfügen

Identifizieren Sie Zugriffsbereiche

Bereiche ermöglichen Ihrer Anwendung, nur den Zugriff auf die Ressourcen anzufordern, die sie benötigt, während Benutzer gleichzeitig die Zugriffsmenge steuern können, die sie Ihrer Anwendung gewähren. Daher kann es eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit geben, die Zustimmung des Benutzers zu erhalten.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, empfehlen wir Ihnen, die Bereiche zu identifizieren, für die Ihre App eine Zugriffsberechtigung benötigt.

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

Abrufen von OAuth 2.0-Zugriffstoken

Die folgenden Schritte zeigen, wie Ihre Anwendung mit dem OAuth 2.0-Server von Google interagiert, um die Zustimmung eines Benutzers zur Ausführung einer API-Anforderung im Namen des Benutzers einzuholen. Ihre Anwendung muss über diese Zustimmung verfügen, bevor sie eine Google-API-Anforderung ausführen kann, für die eine Benutzerautorisierung erforderlich ist.

Schritt 1: Generieren Sie einen Code-Verifizierer und eine Herausforderung

Google unterstützt das Protokoll Proof Key for Code Exchange (PKCE), um den Ablauf der installierten App sicherer zu machen. Für jede Autorisierungsanforderung wird ein eindeutiger Code-Verifizierer erstellt, und sein umgewandelter Wert mit der Bezeichnung "code_challenge" wird an den Autorisierungsserver gesendet, um den Autorisierungscode zu erhalten.

Erstellen Sie den Codeprüfer

Ein code_verifier ist eine kryptografische Zufallszeichenfolge mit hoher Entropie, die die nicht reservierten Zeichen [AZ] / [az] / [0-9] / „-“ / „.“ verwendet. / "_" / "~", mit einer Mindestlänge von 43 Zeichen und einer maximalen Länge von 128 Zeichen.

Der Codeverifizierer sollte genügend Entropie haben, um es unpraktisch zu machen, den Wert zu erraten.

Erstellen Sie die Code-Challenge

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

Methoden zur Generierung von Code-Challenges
S256 (empfohlen) Die Codeherausforderung ist der Base64URL-codierte (ohne Auffüllung) SHA256-Hash des Codeverifizierers.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
schlicht Die Code-Herausforderung ist derselbe Wert wie der oben generierte Code-Verifizierer.
code_challenge = code_verifier

Schritt 2: Senden Sie eine Anfrage an den OAuth 2.0-Server von Google

Um eine Benutzerautorisierung zu erhalten, senden Sie eine Anfrage an den Autorisierungsserver von Google unter https://accounts.google.com/o/oauth2/v2/auth . Dieser Endpunkt verarbeitet die aktive Sitzungssuche, authentifiziert den Benutzer und holt die Zustimmung des Benutzers ein. Der Endpunkt ist nur über SSL zugänglich und lehnt HTTP-Verbindungen (nicht SSL) ab.

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

Parameter
client_id Erforderlich

Die Client-ID für Ihre Anwendung. Diesen Wert finden Sie im API ConsoleCredentials page.

redirect_uri Erforderlich

Legt fest, wie der Autorisierungsserver von Google eine Antwort an Ihre App sendet. Für installierte Apps stehen mehrere Umleitungsoptionen zur Verfügung, und Sie haben Ihre Anmeldeinformationen für die Autorisierung mit Blick auf eine bestimmte Umleitungsmethode eingerichtet.

Der Wert muss genau mit einem der autorisierten Redirect-Umleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie im API ConsoleCredentials pageIhres Clients konfiguriert haben. Wenn dieser Wert keinem autorisierten URI entspricht, erhalten Sie den Fehler „ redirect_uri_mismatch “.

Die folgende Tabelle zeigt den entsprechenden Wert des Parameters „ redirect_uri “ für jede Methode:

redirect_uri -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 unter Ihrer Kontrolle. 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 . Beachten Sie, dass der Pfad mit einem einzelnen Schrägstrich beginnen sollte, was sich von normalen 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 auf einem zufällig verfügbaren Port. Ersetzen Sie port durch die tatsächliche Portnummer, auf der Ihre App lauscht.

Manuelles Kopieren/Einfügen urn:ietf:wg:oauth:2.0:oob
Programmatische Extraktion urn:ietf:wg:oauth:2.0:oob:auto
response_type Erforderlich

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

Setzen Sie den Parameterwert auf code für installierte Anwendungen.

scope Erforderlich

Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Benutzers zugreifen könnte. Diese Werte informieren den Zustimmungsbildschirm, den Google dem Benutzer anzeigt.

Bereiche ermöglichen Ihrer Anwendung, nur den Zugriff auf die Ressourcen anzufordern, die sie benötigt, während Benutzer gleichzeitig die Zugriffsmenge steuern können, die sie Ihrer Anwendung gewähren. Somit besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Zustimmung des Benutzers zu erhalten.

code_challenge Empfohlen

Gibt einen codierten code_verifier an, der beim Austausch des Autorisierungscodes als serverseitige Abfrage verwendet wird. Weitere Informationen finden Sie oben im Abschnitt „ Challenge zum Erstellen von Codes “.

code_challenge_method Empfohlen

Gibt an, welche Methode verwendet wurde, um einen code_verifier zu codieren, der während des Austauschs des Autorisierungscodes verwendet wird. Dieser Parameter muss mit dem oben beschriebenen code_challenge Parameter verwendet werden. Der Wert von code_challenge_method standardmäßig plain , wenn er nicht in der Anforderung vorhanden ist, die eine code_challenge enthält. Die einzigen unterstützten Werte für diesen Parameter sind S256 oder plain .

state Empfohlen

Gibt einen beliebigen Zeichenfolgewert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanforderung 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 ( # ) von „ redirect_uri “ senden, nachdem der Benutzer der Zugriffsanforderung Ihrer Anwendung zugestimmt oder sie abgelehnt hat.

Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Benutzer an die richtige Ressource in Ihrer Anwendung weiterzuleiten, Nonces zu senden und die standortübergreifende Anforderungsfälschung zu verringern. Da Ihre redirect_uri -URI erraten werden kann, kann die Verwendung eines state Ihre Gewissheit erhöhen, dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanforderung ist. Wenn Sie eine zufällige Zeichenfolge generieren oder den Hash eines Cookies oder einen anderen Wert codieren, der den Status des Clients erfasst, können Sie die Antwort validieren, um zusätzlich sicherzustellen, dass die Anfrage und die Antwort aus demselben Browser stammen, was Schutz vor Angriffen wie z. B. standortübergreifenden bietet Fälschung verlangen. Ein Beispiel zum Erstellen und Bestätigen eines state finden Sie in der OpenID Connect -Dokumentation.

login_hint Optional

Wenn Ihre Anwendung weiß, welcher Benutzer versucht, sich zu authentifizieren, kann sie diesen Parameter verwenden, um dem Google-Authentifizierungsserver einen Hinweis zu geben. Der Server verwendet den Hinweis, um den Anmeldeablauf zu vereinfachen, indem er entweder das E-Mail-Feld im Anmeldeformular vorab ausfüllt oder die entsprechende Mehrfach-Anmeldesitzung auswählt.

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

Beispielautorisierungs-URLs

Die Registerkarten unten zeigen Beispiel-Autorisierungs-URLs für die verschiedenen Umleitungs-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 zur besseren Lesbarkeit.

Benutzerdefiniertes URI-Schema

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

Kopieren Einfügen

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&
 client_id=client_id

Programmatische Extraktion

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
 client_id=client_id

Schritt 3: Google fordert den Benutzer zur Zustimmung auf

In diesem Schritt entscheidet der Benutzer, ob er Ihrer Anwendung den gewünschten Zugriff gewährt. In diesem Stadium zeigt Google ein Zustimmungsfenster an, das den Namen Ihrer Anwendung und die Google-API-Dienste anzeigt, für die eine Zugriffsberechtigung mit den Autorisierungsanmeldeinformationen des Benutzers angefordert wird, sowie eine Zusammenfassung der zu gewährenden Zugriffsbereiche. Der Benutzer kann dann zustimmen, Zugriff auf einen oder mehrere Bereiche zu gewähren, die von Ihrer Anwendung angefordert werden, oder die Anforderung ablehnen.

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

Fehler

Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google zeigen möglicherweise benutzerseitige Fehlermeldungen anstelle der erwarteten Authentifizierungs- und Autorisierungsabläufe an. Häufige Fehlercodes und vorgeschlagene Lösungen sind unten aufgeführt.

admin_policy_enforced

Das Google-Konto kann aufgrund der Richtlinien des Google Workspace-Administrators einen oder mehrere angeforderte Bereiche nicht autorisieren. Weitere Informationen dazu, wie ein Administrator den Zugriff auf alle Bereiche oder vertrauliche und eingeschränkte Bereiche einschränken kann, bis der Zugriff Ihrer OAuth-Client-ID ausdrücklich gewährt wird, finden Sie im Hilfeartikel Google Workspace Admin.

disallowed_useragent

Der Autorisierungsendpunkt wird in einem eingebetteten User-Agent angezeigt, der von den OAuth 2.0 -Richtlinien von Google nicht zugelassen wird.

Android

Android-Entwickler können auf diese Fehlermeldung stoßen, wenn sie Autorisierungsanfragen inandroid.webkit.WebView . Entwickler sollten stattdessen Android-Bibliotheken wie Google Sign-In für Android oder AppAuth von OpenID Foundation für Android verwenden .

Webentwickler können auf diesen Fehler stoßen, wenn eine Android-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Benutzer von Ihrer Website zum OAuth 2.0-Autorisierungsendpunkt von Google navigiert. Entwickler sollten das Öffnen allgemeiner Links im standardmäßigen Link-Handler des Betriebssystems zulassen, der sowohl Android-App -Link-Handler als auch die standardmäßige Browser-App umfasst. Die Android Custom Tabs- Bibliothek ist ebenfalls eine unterstützte Option.

iOS

iOS- und macOS-Entwickler können auf diesen Fehler stoßen, wenn sie Autorisierungsanforderungen inWKWebView . Entwickler sollten stattdessen iOS-Bibliotheken wie Google Sign-In für iOS oder AppAuth von OpenID Foundation für iOS verwenden .

Webentwickler können auf diesen Fehler stoßen, wenn eine iOS- oder macOS-App einen allgemeinen Weblink in einem eingebetteten Benutzeragenten öffnet und ein Benutzer von Ihrer Website zum OAuth 2.0-Autorisierungsendpunkt von Google navigiert. Entwickler sollten das Öffnen allgemeiner Links im standardmäßigen Link-Handler des Betriebssystems zulassen, der sowohl universelle Links -Handler als auch die standardmäßige Browser-App umfasst. DieSFSafariViewController Bibliothek ist ebenfalls eine unterstützte Option.

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 Abschnitt Benutzertyp im Hilfeartikel Einrichten Ihres OAuth-Zustimmungsbildschirms.

redirect_uri_mismatch

Die in der Autorisierungsanforderung übergebene redirect_uri -URI stimmt nicht mit einem autorisierten Umleitungs-URI für die OAuth-Client-ID überein. Überprüfen Sie autorisierte Umleitungs-URIs im Google API Console Credentials page.

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

Schritt 4: Bearbeiten Sie die Antwort des OAuth 2.0-Servers

Die Art und Weise, wie Ihre Anwendung die Autorisierungsantwort empfängt, hängt von dem verwendeten Umleitungs-URI-Schema ab. Unabhängig vom Schema enthält die Antwort entweder einen Autorisierungscode ( code ) oder einen Fehler ( error ). Beispielsweise zeigt error=access_denied an, dass der Benutzer die Anfrage abgelehnt hat.

Wenn der Benutzer 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 Zugriffstoken austauschen

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

Felder
client_id Die aus dem API ConsoleCredentials pageerhaltene Client-ID.
client_secret Das vom API ConsoleCredentials pageabgerufene Client-Geheimnis.
code Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wurde.
code_verifier Der Codeverifizierer, den Sie in Schritt 1 erstellt haben.
grant_type Wie in der OAuth 2.0-Spezifikation definiert , muss der Wert dieses Felds auf authentication_code gesetzt authorization_code .
redirect_uri Einer der Umleitungs-URIs, die für Ihr Projekt in API ConsoleCredentials page für die angegebene client_id .

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=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
grant_type=authorization_code

Google antwortet auf diese Anfrage, indem es ein JSON-Objekt zurückgibt, das ein kurzlebiges Zugriffstoken und ein Aktualisierungstoken enthält.

Die Antwort enthält die folgenden Felder:

Felder
access_token Das Token, das Ihre Anwendung sendet, um eine Google-API-Anfrage zu autorisieren.
expires_in Die verbleibende Lebensdauer des Zugriffstokens in Sekunden.
id_token Hinweis: Diese Eigenschaft wird nur zurückgegeben, wenn Ihre Anfrage einen Identitätsbereich wie openid , profile oder email enthielt. Der Wert ist ein JSON Web Token (JWT), das digital signierte Identitätsinformationen über den Benutzer enthält.
refresh_token Ein Token, mit dem Sie ein neues Zugriffstoken abrufen können. Aktualisierungstoken sind gültig, bis der Benutzer den Zugriff widerruft. Beachten Sie, dass Aktualisierungstoken immer für installierte Anwendungen zurückgegeben werden.
scope Die vom access_token gewährten Zugriffsbereiche, ausgedrückt als Liste von durch Leerzeichen getrennten Zeichenfolgen mit Berücksichtigung der Groß- und Kleinschreibung.
token_type Der Typ des zurückgegebenen Tokens. Zu diesem Zeitpunkt ist der Wert dieses Felds immer auf Bearer gesetzt.

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

Aufrufen von Google-APIs

Nachdem Ihre Anwendung ein Zugriffstoken erhalten hat, können Sie das Token verwenden, um im Namen eines bestimmten Nutzerkontos Aufrufe an eine Google-API zu tätigen, wenn der/die von der API erforderliche(n) Zugriffsbereich(e) gewährt wurden. Schließen Sie dazu das Zugriffstoken in eine Anforderung an die API ein, indem Sie entweder einen access_token -Abfrageparameter oder einen Authorization -HTTP-Header- Bearer -Wert einschließen. Wenn möglich, ist der HTTP-Header vorzuziehen, da Abfragezeichenfolgen in der Regel in Serverprotokollen sichtbar sind. In den meisten Fällen können Sie eine Clientbibliothek verwenden, um Ihre Aufrufe an Google-APIs einzurichten (z. B. beim Aufrufen der Drive Files API ).

Auf dem OAuth 2.0 Playground können Sie alle Google-APIs ausprobieren und deren Umfang anzeigen.

HTTP-GET-Beispiele

Ein Aufruf des Endpunkts „ drive.files (der Drive Files-API) mit dem HTTP-Header „ Authorization: Bearer “ könnte wie folgt aussehen. Beachten Sie, dass Sie Ihr eigenes Zugriffstoken angeben müssen:

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 Benutzer, der den access_token verwendet:

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

curl Beispiele

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

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

Oder alternativ die Parameteroption Abfragezeichenfolge:

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

Aktualisieren eines Zugriffstokens

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

Um ein Zugriffstoken zu aktualisieren, sendet Ihre Anwendung eine HTTPS- POST -Anforderung an den Autorisierungsserver von Google ( https://oauth2.googleapis.com/token ), die die folgenden Parameter enthält:

Felder
client_id Die aus dem API Consoleerhaltene Client-ID.
client_secret Das vom API Consoleerhaltene Client-Geheimnis. (Das 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 Felds auf refresh_token .
refresh_token Das vom Autorisierungscodeaustausch 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 Benutzer den gewährten Zugriff auf die Anwendung nicht widerrufen hat, gibt der Token-Server 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 ausgegebenen Aktualisierungstoken begrenzt ist. ein Limit pro Client/Benutzer-Kombination und ein weiteres pro Benutzer für alle Clients. Sie sollten Aktualisierungstoken langfristig speichern und sie so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstoken anfordert, stößt sie möglicherweise an diese Grenzwerte. In diesem Fall funktionieren ältere Aktualisierungstoken nicht mehr.

Widerrufen eines Tokens

In einigen Fällen möchte ein Benutzer möglicherweise den Zugriff auf eine Anwendung widerrufen. Ein Benutzer kann den Zugriff widerrufen, indem er die Kontoeinstellungen besucht. Weitere Informationen finden Sie im Abschnitt Website- oder App-Zugriff entfernen des Supportdokuments Websites und Apps von Drittanbietern mit Zugriff auf Ihr Konto .

Es ist auch möglich, dass eine Anwendung den ihr erteilten Zugriff programmgesteuert entzieht. Der programmgesteuerte Widerruf ist in Fällen wichtig, in denen ein Benutzer das Abonnement abbestellt, eine Anwendung entfernt oder sich die von einer App benötigten API-Ressourcen erheblich geändert haben. Mit anderen Worten, ein Teil des Entfernungsprozesses kann eine API-Anforderung umfassen, um sicherzustellen, dass die der Anwendung zuvor gewährten Berechtigungen entfernt werden.

Um ein Token programmgesteuert zu widerrufen, stellt Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke und schließt 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 über ein entsprechendes Aktualisierungstoken verfügt, wird das Aktualisierungstoken ebenfalls widerrufen.

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

Weiterführende Lektüre

Die IETF Best Current Practice OAuth 2.0 for Native Apps legt viele der hier dokumentierten Best Practices fest.