In diesem Dokument wird erläutert, wie auf Geräten wie Smartphones, Tablets und Computern installierte Anwendungen OAuth 2.0-Endpunkte von Google verwenden, um den Zugriff auf Google APIs 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. Beispielsweise kann eine Anwendung mithilfe von OAuth 2.0 die Berechtigung von Nutzern zum Speichern von Dateien in Google Drive einholen.
Installierte Anwendungen werden auf einzelne Geräte verteilt und es wird davon ausgegangen, dass diese Anwendungen keine Secrets behalten dürfen. Sie können auf Google APIs zugreifen, während der Nutzer die App verwendet oder die App im Hintergrund ausgeführt wird.
Dieser Autorisierungsvorgang ähnelt dem für Webserveranwendungen. Der Hauptunterschied besteht darin, dass installierte Anwendungen den Systembrowser öffnen und einen lokalen Weiterleitungs-URI angeben müssen, um die Antworten vom Autorisierungsserver von Google zu verarbeiten.
Alternativen
Für mobile Apps empfehlen wir Google Log-in für Android oder iOS. Die Google Log-in-Clientbibliotheken verarbeiten die Authentifizierung und Nutzerautorisierung 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 eingeschränkte Eingabefunktionen bieten, z. B. Fernsehgeräte, Spielekonsolen, 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 Beispiele
Wir empfehlen die folgenden Bibliotheken und Beispiele, um dich bei der Implementierung des in diesem Dokument beschriebenen OAuth 2.0-Vorgangs zu unterstützen:
- AppAuth for Android-Bibliothek
- AppAuth for iOS-Bibliothek
- OAuth für Apps: Windows-Beispiele
Voraussetzungen
Die APIs für Ihr Projekt aktivieren
Jede Anwendung, die Google APIs aufruft, muss diese APIs in API Consoleaktivieren.
So aktivieren Sie eine API für Ihr Projekt:
- Open the API Library in Google API Console.
- If prompted, select a project, or create a new one.
- In API Library sind alle verfügbaren APIs nach Produktfamilie und Beliebtheit gruppiert aufgeführt. Wenn die gewünschte API nicht in der Liste aufgeführt ist, suchen Sie sie oder klicken Sie in der zugehörigen Produktfamilie auf Alle ansehen.
- Wählen Sie die API aus, die Sie aktivieren möchten, und klicken Sie auf die Schaltfläche Aktivieren.
- If prompted, enable billing.
- 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 über Autorisierungsanmeldedaten verfügen, die die Anwendung beim OAuth 2.0-Server von Google identifizieren. 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.
- Go to the Credentials page.
- Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
- 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 Clienttyp aus, benennen Sie den OAuth-Client und legen Sie die anderen Felder im Formular entsprechend fest.
Android
- Wählen Sie den Anwendungstyp Android aus.
- Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird auf der Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
- Geben Sie den Paketnamen Ihrer Android-App ein. Dieser Wert ist in Ihrer App-Manifestdatei im
Attribut
package
des Elements<manifest>
definiert. - 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 Ihre Signaturschlüssel verwalten, verwenden Sie das in Java enthaltene Dienstprogramm keytool, um Zertifikatsinformationen in einem für Menschen lesbaren Format auszudrucken. Kopieren Sie den Wert
SHA1
im AbschnittCertificate fingerprints
der Keytool-Ausgabe. Weitere Informationen finden Sie in der Dokumentation zu Google APIs für Android unter Client authentifizieren.
- Optional: Bestätigen Sie die Inhaberschaft Ihrer Android-App.
- Klicken Sie auf Erstellen.
iOS
- Wählen Sie den Anwendungstyp iOS aus.
- Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird auf der Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
- Geben Sie den Bundle-Identifikator für Ihre Anwendung ein. Die Bundle-ID ist der Wert des Schlüssels CFBundleIdentifier in der Ressourcendatei mit der Informationseigenschaftsliste Ihrer Anwendung (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 im Abschnitt „Allgemeine Informationen“ der Seite „App-Informationen“ für die App auf der App Store Connect-Website von Apple angezeigt.
- (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.
- Öffne die Apple App Store App auf deinem iOS- oder iPadOS-Gerät.
- Suchen Sie nach Ihrer App.
- Wählen Sie die Schaltfläche „Teilen“ (quadratisches Symbol und Pfeil nach oben).
- Wählen Sie Link kopieren aus.
- 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
- (Optional)
Gib deine Team-ID ein. Weitere Informationen finden Sie in der Dokumentation zum Apple-Entwicklerkonto unter Team-ID finden.
- Klicken Sie auf Erstellen.
UWP
- Wählen Sie den Anwendungstyp Universelle Windows-Plattform aus.
- Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird auf der Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
- Geben Sie die 12-stellige Microsoft Store-ID Ihrer App ein. Sie finden diesen Wert im Microsoft-Partnercenter im Abschnitt „App-Verwaltung“ auf der Seite App-Identität.
- Klicken Sie auf Erstellen.
Bei UWP-Apps darf das benutzerdefinierte URI-Schema nicht länger als 39 Zeichen sein.
Benutzerdefiniertes URI-Schema (Android, iOS, UWP)
Benutzerdefinierte URI-Schemas sind eine Form von Deeplinks, bei denen ein benutzerdefiniertes Schema zum Öffnen Ihrer App verwendet wird.
Alternative zu benutzerdefinierten URI-Schemas unter AndroidVerwende das Google Log-in for Android SDK, das die OAuth 2.0-Antwort direkt an deine App sendet. Dadurch ist kein Weiterleitungs-URI erforderlich.
So migrierst du zum Google Log-in for Android SDK
Wenn du derzeit ein benutzerdefiniertes Schema für die OAuth-Integration unter Android verwendest, musst du die folgenden Aktionen ausführen, um vollständig zum empfohlenen Google Log-in for Android SDK zu migrieren:
- Aktualisieren Sie Ihren Code, um das Google Log-in SDK zu verwenden.
- Unterstützung für benutzerdefinierte Schemas in der Google API Console deaktivieren.
Führen Sie die folgenden Schritte aus, um zum Google Log-in Android SDK zu migrieren:
-
Aktualisieren Sie Ihren Code, um das Google Log-in Android SDK zu verwenden:
-
Sehen Sie in Ihrem Code nach, wohin Sie eine Anfrage an den OAuth 2.0-Server von Google senden. Wenn Sie ein benutzerdefiniertes Schema verwenden, sieht Ihre Anfrage so aus:
https://accounts.google.com/o/oauth2/v2/auth? scope=<SCOPES>& response_type=code& &state=<STATE>& redirect_uri=com.example.app:/oauth2redirect& client_id=<CLIENT_ID>
com.example.app:/oauth2redirect
ist der Weiterleitungs-URI für benutzerdefinierte Schemas im obigen Beispiel. Weitere Informationen zum Format des benutzerdefinierten URI-Schemawerts finden Sie in der Parameterdefinitionredirect_uri
. -
Notiere dir die Anfrageparameter
scope
undclient_id
, die du zum Konfigurieren des Google Log-in SDK benötigst. -
Folgen Sie der Anleitung unter
Google Log-in in Ihre Android-App einbinden, um das SDK einzurichten. Sie können den Schritt OAuth 2.0-Client-ID Ihres Back-End-Servers abrufen überspringen, da Sie die
client_id
wiederverwenden würden, die Sie im vorherigen Schritt abgerufen haben. -
Folgen Sie der Anleitung unter
Serverseitigen API-Zugriff aktivieren. Dazu gehören die folgenden Schritte:
-
Verwenden Sie die Methode
getServerAuthCode
, um einen Autorisierungscode für die Bereiche abzurufen, für die Sie eine Berechtigung anfordern. - Senden Sie den Authentifizierungscode an das Back-End Ihrer Anwendung, um ihn gegen ein Zugriffs- und Aktualisierungstoken auszutauschen.
- Verwenden Sie das abgerufene Zugriffstoken, um im Namen des Nutzers Google APIs aufzurufen.
-
Verwenden Sie die Methode
-
Sehen Sie in Ihrem Code nach, wohin Sie eine Anfrage an den OAuth 2.0-Server von Google senden. Wenn Sie ein benutzerdefiniertes Schema verwenden, sieht Ihre Anfrage so aus:
-
Deaktivieren Sie die Unterstützung für benutzerdefinierte Schemas in der Google API Console:
- Rufen Sie die Liste mit den OAuth 2.0-Anmeldedaten auf und wählen Sie Ihren Android-Client aus.
- Gehen Sie zum Abschnitt Erweiterte Einstellungen, entfernen Sie das Häkchen aus dem Kästchen Benutzerdefiniertes URI-Schema aktivieren und klicken Sie auf Speichern, um die Unterstützung benutzerdefinierter URI-Schemas zu deaktivieren.
Benutzerdefiniertes URI-Schema aktivieren
Wenn die empfohlene Alternative für Sie nicht in Frage kommt, können Sie benutzerdefinierte URI-Schemas für Ihren Android-Client aktivieren. Folgen Sie dazu der Anleitung unten:- Rufen Sie die Liste mit den OAuth 2.0-Anmeldedaten auf und wählen Sie Ihren Android-Client aus.
- Gehen Sie zum Bereich Erweiterte Einstellungen, klicken Sie auf das Kästchen Benutzerdefiniertes URI-Schema aktivieren und dann auf Speichern, um die Unterstützung für benutzerdefinierte URI-Schemas zu aktivieren.
Verwende die Chrome Identity API, die die OAuth 2.0-Antwort direkt an deine Anwendung sendet. Ein Weiterleitungs-URI ist somit nicht mehr erforderlich.
App-Inhaberschaft bestätigen (Android, Chrome)
Sie können die Inhaberschaft Ihrer App bestätigen, um das Risiko eines App-Identitätsdiebstahls zu verringern.
Android
Für den Bestätigungsvorgang kannst du dein Google Play-Entwicklerkonto verwenden, wenn du eines hast und deine App in der Google Play Console registriert ist. Für eine erfolgreiche Überprüfung müssen die folgenden Anforderungen erfüllt sein:
- Du musst in der Google Play Console eine registrierte App mit demselben Paketnamen und SHA-1-Signaturzertifikat-Fingerabdruck wie der Android OAuth-Client haben, für den du die Überprüfung vornimmst.
- Sie benötigen die Administratorberechtigung für die App in der Google Play Console. Weitere Informationen zur Zugriffsverwaltung in der Google Play Console
Klicken Sie im Abschnitt Inhaberschaft der App bestätigen des Android-Clients auf die Schaltfläche Inhaberschaft bestätigen, um den Bestätigungsprozess abzuschließen.
Wenn die Überprüfung erfolgreich war, wird eine Benachrichtigung angezeigt. Andernfalls wird eine Fehleraufforderung angezeigt.
So beheben Sie eine fehlgeschlagene Bestätigung:
- Die App, die Sie bestätigen möchten, muss in der Google Play Console registriert sein.
- Prüfen Sie, ob Sie in der Google Play Console die Administratorberechtigung für die App haben.
Chrome
Für den Bestätigungsvorgang benötigen Sie Ihr Chrome Web Store-Entwicklerkonto. Für eine erfolgreiche Überprüfung müssen die folgenden Anforderungen erfüllt sein:
- Im Chrome Web Store-Entwickler-Dashboard muss ein registrierter Artikel mit derselben Artikel-ID wie der OAuth-Client der Chrome-Erweiterung vorhanden sein, für den Sie die Überprüfung durchführen.
- Sie müssen Publisher für den Chrome Web Store-Artikel sein. Weitere Informationen zur Zugriffsverwaltung im Chrome Web Store-Entwickler-Dashboard.
Klicken Sie im Abschnitt Inhaberschaft der App bestätigen des Clients für Chrome-Erweiterungen auf die Schaltfläche Inhaberschaft bestätigen, um den Bestätigungsvorgang abzuschließen.
Hinweis: Warten Sie einige Minuten, bevor Sie den Bestätigungsvorgang abschließen, nachdem Sie Zugriff auf Ihr Konto gewährt haben.
Wenn die Überprüfung erfolgreich war, wird eine Benachrichtigung angezeigt. Andernfalls wird eine Fehleraufforderung angezeigt.
So beheben Sie eine fehlgeschlagene Bestätigung:
- Achte darauf, dass im Chrome Web Store-Entwickler-Dashboard ein registrierter Artikel mit derselben Artikel-ID wie der OAuth-Client der Chrome-Erweiterung vorhanden ist, für den du die Bestätigung durchführst.
- Sie müssen ein Publisher der App sein. Sie müssen also entweder der jeweilige Publisher der App oder ein Mitglied des Gruppen-Publishers der App sein. Weitere Informationen zur Zugriffsverwaltung im Chrome Web Store-Entwickler-Dashboard
- Wenn du deine Gruppen-Publisher-Liste gerade aktualisiert hast, sieh nach, ob die Gruppen-Publisher-Mitgliederliste mit dem Chrome Web Store-Entwickler-Dashboard synchronisiert ist. Weitere Informationen zum Synchronisieren Ihrer Mitgliederliste des Verlags oder Webpublishers
Loopback-IP-Adresse (macOS, Linux, Windows-Desktop)
Damit der Autorisierungscode über diese URL empfangen werden kann, muss Ihre Anwendung den lokalen Webserver überwachen. Das ist auf vielen, aber nicht auf allen Plattformen möglich. Dies ist jedoch der empfohlene Mechanismus zum Abrufen des Autorisierungscodes, sofern deine Plattform dies unterstützt.
Wenn deine App die Autorisierungsantwort erhält, sollte sie aus Gründen der Nutzerfreundlichkeit mit einer HTML-Seite reagieren, 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 | Legen Sie den Anwendungstyp auf Desktop-App fest. |
Manuell kopieren/einfügen
Zugriffsbereiche identifizieren
Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig können Nutzer den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Daher kann es eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit des Einholens der Nutzereinwilligung geben.
Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche identifizieren, für die Ihre App eine Zugriffsberechtigung 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-Zugriffstokens 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: Code-Verifizierer und Challenge generieren
Google unterstützt das Protokoll Proof Key for Code Exchange (PKCE), um den Ablauf der installierten Anwendung sicherer zu machen. Für jede Autorisierungsanfrage wird ein eindeutiger Codeprüfer erstellt. Der transformierte Wert namens „code_challenge“ wird an den Autorisierungsserver gesendet, um den Autorisierungscode abzurufen.
Codeprüfung erstellen
Ein code_verifier
ist ein kryptografischer Zufallsstring mit hoher Entropie, der die nicht reservierten Zeichen [A–Z] / [a–z] / [0–9] / „-“ / „.“ / „_“ / „~“ mit einer Mindestlänge von 43 Zeichen und einer maximalen Länge von 128 Zeichen enthält.
Der Codeprüfer sollte genügend Entropie haben, um den Wert unpraktisch zu erraten.
Code-Challenge erstellen
Es werden zwei Methoden zum Erstellen der Code-Abfrage unterstützt.
Methoden zur Generierung von Code-Challenges | |
---|---|
S256 (empfohlen) | Die Code-Challenge ist der Base64URL-codierte SHA256-Hash der Code-Überprüfung (ohne Padding).
|
Einfach | Die Code-Abfrage entspricht dem oben generierten Code-Verifizierer.
|
Schritt 2: Anfrage an den OAuth 2.0-Server von Google senden
Senden Sie eine Anfrage an den Autorisierungsserver von Google unter https://accounts.google.com/o/oauth2/v2/auth
, um die Nutzerautorisierung zu erhalten. Dieser Endpunkt verarbeitet die aktive Sitzungssuche, authentifiziert den Nutzer und holt die Nutzereinwilligung ein. Der Endpunkt ist nur über SSL zugänglich und lehnt HTTP-Verbindungen (Nicht-SSL) ab.
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 der API Console Credentials page. |
||||||
redirect_uri |
Erforderlich
Legt fest, wie der Autorisierungsserver von Google eine Antwort an Ihre Anwendung sendet. Für installierte Apps sind mehrere Weiterleitungsoptionen verfügbar. Bei der Einrichtung Ihrer Autorisierungsdaten sollten Sie eine bestimmte Weiterleitungsmethode berücksichtigen. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den du in der API Console
Credentials pagedeines Clients konfiguriert hast. Wenn dieser Wert mit keinem autorisierten URI übereinstimmt, wird der Fehler In der folgenden Tabelle sehen Sie den entsprechenden
|
||||||
response_type |
Erforderlich
Bestimmt, ob der Google OAuth 2.0-Endpunkt einen Autorisierungscode zurückgibt. Legen Sie den Parameterwert für installierte Anwendungen auf |
||||||
scope |
Erforderlich
Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen angeben, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte beziehen sich auf den Zustimmungsbildschirm, den Google dem Nutzer anzeigt. Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig können Nutzer den Umfang des Zugriffs auf Ihre Anwendung steuern. Daher besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen. |
||||||
code_challenge |
Empfohlen
Gibt eine codierte |
||||||
code_challenge_method |
Empfohlen
Gibt an, welche Methode zum Codieren eines |
||||||
state |
Empfohlen
Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers beizubehalten.
Nachdem der Nutzer der Zugriffsanfrage Ihrer Anwendung zugestimmt oder sie abgelehnt hat, gibt der Server genau den Wert zurück, den Sie als Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung weiterzuleiten, Nonces zu senden und die websiteübergreifende Anfragefälschung zu mindern. Da Ihr |
||||||
login_hint |
Optional
Wenn Ihre Anwendung weiß, welcher Nutzer zu authentifizieren versucht, kann dieser Parameter verwendet werden, um dem Google-Authentifizierungsserver einen Hinweis bereitzustellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen, indem er das E-Mail-Feld im Anmeldeformular vorab ausfüllt oder die entsprechende Mehrfachanmeldungssitzung auswählt. Legen Sie den Parameterwert auf eine E-Mail-Adresse oder eine |
Beispiele für Autorisierungs-URLs
Die folgenden Tabs enthalten Beispiel-Autorisierungs-URLs für die verschiedenen Weiterleitungs-URI-Optionen.
Die URLs sind bis auf den Wert des redirect_uri
-Parameters identisch. Die URLs enthalten außerdem die erforderlichen response_type
- und client_id
-Parameter sowie den optionalen state
-Parameter. Jede URL enthält zur besseren Lesbarkeit Zeilenumbrüche und Leerzeichen.
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
Schritt 3: Google fordert den Nutzer zur Einwilligung auf
In diesem Schritt entscheidet der Nutzer, ob er Ihrer Anwendung den angeforderten Zugriff gewährt. In dieser Phase zeigt Google ein Einwilligungsfenster mit dem Namen Ihrer Anwendung und den Google API-Diensten an, für die die Berechtigung für den Zugriff mit den Autorisierungsanmeldedaten des Nutzers angefordert wird. Außerdem wird eine Zusammenfassung der Zugriffsbereiche angezeigt, die gewährt werden sollen. Der Nutzer kann dann zustimmen, Zugriff auf einen oder mehrere von Ihrer Anwendung angeforderte Bereiche zu gewähren, oder die Anfrage ablehnen.
Ihre Anwendung muss in dieser Phase nichts weiter tun, da sie auf die Antwort des OAuth 2.0-Servers von Google wartet, die angibt, ob der Zugriff gewährt wurde. Diese Antwort wird im folgenden Schritt erläutert.
Fehler
Bei Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google werden möglicherweise Fehlermeldungen für Nutzer anstelle der erwarteten Authentifizierungs- und Autorisierungsabläufe angezeigt. Häufige Fehlercodes und Lösungsvorschläge sind unten aufgeführt.
admin_policy_enforced
Das Google-Konto kann einen oder mehrere angeforderte Bereiche aufgrund der Richtlinien des jeweiligen Google Workspace-Administrators nicht autorisieren. Im Hilfeartikel Zugriff externer und interner Apps auf Google Workspace-Daten steuern finden Sie weitere Informationen dazu, wie ein Administrator den Zugriff auf alle oder vertrauliche und eingeschränkte Bereiche einschränken kann, bis der OAuth-Client-ID 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
Android-Entwickler können diese Fehlermeldung sehen, wenn sie Autorisierungsanfragen in android.webkit.WebView
öffnen.
Entwickler sollten stattdessen Android-Bibliotheken wie Google Log-in for Android oder AppAuth for Android der OpenID Foundation verwenden.
Dieser Fehler kann bei Webentwicklern auftreten, 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 navigiert. Entwickler sollten zulassen, dass allgemeine Links im standardmäßigen Link-Handler des Betriebssystems geöffnet werden. Dazu gehören sowohl Android-App-Links-Handler oder die Standard-Browser-App. Die Bibliothek Benutzerdefinierte Tabs ist ebenfalls eine unterstützte Option.
iOS
Dieser Fehler kann beim Öffnen von Autorisierungsanfragen in WKWebView
für iOS- und macOS-Entwickler auftreten.
Entwickler sollten stattdessen iOS-Bibliotheken wie Google Log-in for iOS oder AppAuth for iOS der OpenID Foundation verwenden.
Bei Webentwicklern kann dieser Fehler auftreten, wenn eine iOS- oder macOS-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von Ihrer Website zum OAuth 2.0-Autorisierungsendpunkt von Google navigiert. Entwickler sollten zulassen, dass allgemeine Links im standardmäßigen Link-Handler des Betriebssystems geöffnet werden, der sowohl Universal-Links-Handler oder die Standard-Browser-App umfasst. Die Bibliothek SFSafariViewController
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 einschränkt. Weitere Informationen zu dieser Konfigurationsoption finden Sie im Hilfeartikel „OAuth-Zustimmungsbildschirm einrichten“ im Abschnitt Nutzertyp.
invalid_grant
Wenn Sie eine Codeprüfung und eine Codeabfrage verwenden, ist der Parameter code_callenge
ungültig oder fehlt. Prüfen Sie, ob der Parameter code_challenge
richtig festgelegt ist.
Beim Aktualisieren eines Zugriffstokens ist das Token möglicherweise abgelaufen oder wurde entwertet. Authentifizieren Sie den Nutzer noch einmal und bitten Sie ihn um seine Zustimmung, um neue Tokens zu erhalten. Wenn dieser Fehler weiterhin angezeigt wird, prüfen Sie, ob Ihre Anwendung richtig konfiguriert wurde und Sie in Ihrer Anfrage die richtigen Tokens und Parameter 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 die autorisierten Weiterleitungs-URIs in der 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 Aktualisieren deiner Integration findest du in der Migrationsanleitung.
invalid_request
Es gab ein Problem mit Ihrer Anfrage. Dafür kann es mehrere Gründe geben:
- Die Anfrage war nicht richtig formatiert
- In der Anfrage fehlten erforderliche Parameter
- In der Anfrage wird eine Autorisierungsmethode verwendet, die von Google nicht unterstützt wird. Prüfen, ob die OAuth-Einbindung eine empfohlene Integrationsmethode verwendet
- Für den Weiterleitungs-URI wird ein benutzerdefiniertes Schema verwendet : Wenn die Fehlermeldung Benutzerdefiniertes URI-Schema wird in Chrome-Apps nicht unterstützt oder Benutzerdefiniertes URI-Schema ist für Ihren Android-Client nicht aktiviert angezeigt wird, verwenden Sie ein benutzerdefiniertes URI-Schema, das von Chrome-Apps nicht unterstützt wird und unter Android standardmäßig deaktiviert ist. Weitere Informationen zu Alternativen für benutzerdefinierte URI-Schemas
Schritt 4: OAuth 2.0-Serverantwort verarbeiten
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
). error=access_denied
gibt beispielsweise an, 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 gegen Aktualisierungs- und Zugriffstokens austauschen
Wenn Sie einen Autorisierungscode gegen ein Zugriffstoken austauschen möchten, rufen Sie den Endpunkt https://oauth2.googleapis.com/token
auf und legen Sie die folgenden Parameter fest:
Felder | |
---|---|
client_id |
Die aus dem API Console Credentials pageabgerufene Client-ID. |
client_secret |
Der aus dem API Console Credentials pageabgerufene Clientschlüssel. |
code |
Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wurde. |
code_verifier |
Die Codeprüfung, die Sie in Schritt 1 erstellt haben. |
grant_type |
Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Felds auf authorization_code festgelegt werden. |
redirect_uri |
Einer der Weiterleitungs-URIs, die für Ihr Projekt in API Console
Credentials page für den angegebenen 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 mit der Rückgabe eines JSON-Objekts, das ein kurzlebiges Zugriffstoken und ein Aktualisierungstoken enthält.
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 enthielt. Der Wert ist ein JSON Web Token (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 |
Die durch access_token gewährten Zugriffsbereiche, ausgedrückt als Liste von durch Leerzeichen getrennten Strings unter Beachtung der Groß- und Kleinschreibung. |
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 abgerufen hat, können Sie mit dem Token im Namen eines bestimmten Nutzerkontos eine Google API aufrufen, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein. Dazu fügen Sie entweder einen access_token
-Abfrageparameter oder den Bearer
-Wert eines Authorization
-HTTP-Headers ein. Der HTTP-Header ist nach Möglichkeit zu bevorzugen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen können Sie Aufrufe an Google APIs mithilfe einer Clientbibliothek einrichten, z. B. beim Aufrufen der Drive Files API.
Du kannst alle Google APIs testen und ihre Bereiche im OAuth 2.0 Playground ansehen.
HTTP GET-Beispiele
Ein Aufruf an den Endpunkt
drive.files
(die Drive Files API) mit dem HTTP-Header Authorization: Bearer
könnte so 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 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
-Befehlszeilenanwendung testen. Im folgenden Beispiel wird die HTTP-Header-Option (bevorzugt) verwendet:
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Alternativ können Sie die Parameteroption des Abfragestrings verwenden:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Zugriffstokens 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 dass der Nutzer um eine Berechtigung gebeten wird (auch wenn der Nutzer nicht anwesend ist), wenn Sie Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.
Zum Aktualisieren eines Zugriffstokens sendet Ihre Anwendung eine HTTPS-POST
-Anfrage mit den folgenden Parametern an den Autorisierungsserver https://oauth2.googleapis.com/token
von Google:
Felder | |
---|---|
client_id |
Die vom API Consoleabgerufene Client-ID. |
client_secret |
Der vom API Consoleabgerufene Clientschlüssel.
(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 festgelegt werden. |
refresh_token |
Das vom Austausch des Autorisierungscodes 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 den der Anwendung gewährten Zugriff nicht widerrufen 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" }
Die Anzahl der ausgegebenen Aktualisierungstokens ist begrenzt: ein Limit pro Client/Nutzer-Kombination und ein weiteres pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens langfristig aufbewahren und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits überschritten werden. Ältere Aktualisierungstokens funktionieren in diesem Fall nicht mehr.
Token widerrufen
Manchmal möchte ein Nutzer den Zugriff einer App widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen findest du im Supportdokument Website- oder App-Zugriff entfernen auf Websites und Apps von Drittanbietern mit Zugriff auf dein Konto.
Eine Anwendung kann den ihr gewährten Zugriff auch programmatisch widerrufen. Der programmatische Widerruf ist wichtig, wenn ein Nutzer das Abo kündigt, eine Anwendung entfernt oder sich die für eine Anwendung erforderlichen API-Ressourcen erheblich geändert haben. Mit anderen Worten: Ein Teil des Entfernungsprozesses kann eine API-Anfrage beinhalten, mit der sichergestellt wird, dass die zuvor der Anwendung gewährten Berechtigungen entfernt werden.
Zum programmatischen Widerrufen eines Tokens sendet Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke
und nimmt das Token als Parameter auf:
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 es sich bei dem Token um ein Zugriffstoken handelt und es über ein entsprechendes Aktualisierungstoken verfügt, wird auch das Aktualisierungstoken widerrufen.
Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der HTTP-Statuscode der Antwort 200
. Für Fehlerbedingungen wird der HTTP-Statuscode 400
zusammen mit einem Fehlercode zurückgegeben.
Weiterführende Literatur
In der aktuellen IETF-Best Practice OAuth 2.0 für native Apps sind viele der hier dokumentierten Best Practices enthalten.