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önnen Sie prüfen, ob Sie den richtigen Ablauf für Ihre Anwendung ausgewählt haben.

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:

1. Open the API Library in Google API Console.
2. If prompted, select a project, or create a new one.
3. 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.
4. Wählen Sie die API aus, die Sie aktivieren möchten, und klicken Sie 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 ü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.

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 Clienttyp aus, benennen Sie den OAuth-Client und legen Sie die anderen Felder im Formular entsprechend fest.

Android

1. Wählen Sie den Anwendungstyp Android aus.
2. 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.
3. Geben Sie den Paketnamen Ihrer Android-App ein. Dieser Wert ist in Ihrer App-Manifestdatei im Attribut package des Elements <manifest> 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 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 Abschnitt Certificate fingerprints der Keytool-Ausgabe. Weitere Informationen finden Sie in der Dokumentation zu Google APIs für Android unter Client authentifizieren.
5. Optional: Bestätigen Sie die Inhaberschaft Ihrer Android-App.
6. 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 auf der Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
3. 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.
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. Wählen Sie die Schaltfläche „Teilen“ (quadratisches Symbol 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)

   Gib deine Team-ID ein. Weitere Informationen finden Sie in der Dokumentation zum Apple-Entwicklerkonto unter Team-ID finden.

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 der 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 im Abschnitt „App-Verwaltung“ auf der Seite App-Identität.
4. 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.

Wichtig:Benutzerdefinierte URI-Schemas werden in neuen Chrome-Apps nicht mehr unterstützt und sind bei neuen Android-Clients standardmäßig deaktiviert, da das Risiko des Identitätsdiebstahls bei Apps besteht.

Alternative zu benutzerdefinierten URI-Schemas unter Android

Verwende 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:

1. Aktualisieren Sie Ihren Code, um das Google Log-in SDK zu verwenden.
2. Unterstützung für benutzerdefinierte Schemas in der Google API Console deaktivieren.

Hinweis:Sie sollten Ihre Codeaktualisierungen unter Berücksichtigung der Zeit bis zur Einführung auf Ihrer Nutzerbasis oder auf älteren Geräten bereitstellen, bevor Sie die Unterstützung für benutzerdefinierte Schemas in der Google API Console deaktivieren. So vermeiden Sie, dass Nutzer eine invalid_request-Fehlermeldung erhalten, wenn sie versuchen, Ihre App zu verwenden.

Führen Sie die folgenden Schritte aus, um zum Google Log-in Android SDK zu migrieren:

1. Aktualisieren Sie Ihren Code, um das Google Log-in Android SDK zu verwenden:
   1. 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 Parameterdefinition redirect_uri.
   2. Notiere dir die Anfrageparameter scope und client_id, die du zum Konfigurieren des Google Log-in SDK benötigst.
      Hinweis:Wenn du die Bibliothek eines Drittanbieters verwendest, findest du diese Informationen in der Konfigurationsdatei der Bibliothek.
   3. 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.
   4. Folgen Sie der Anleitung unter Serverseitigen API-Zugriff aktivieren. Dazu gehören die folgenden Schritte:
      1. Verwenden Sie die Methode getServerAuthCode, um einen Autorisierungscode für die Bereiche abzurufen, für die Sie eine Berechtigung anfordern.
      2. Senden Sie den Authentifizierungscode an das Back-End Ihrer Anwendung, um ihn gegen ein Zugriffs- und Aktualisierungstoken auszutauschen.
      3. Verwenden Sie das abgerufene Zugriffstoken, um im Namen des Nutzers Google APIs aufzurufen.
      Hinweis: Wenn für Ihre Anwendung kein Offlinezugriff erforderlich ist, folgen Sie stattdessen dieser Anleitung, um den clientseitigen API-Zugriff anzufordern.
2. Deaktivieren Sie die Unterstützung für benutzerdefinierte Schemas in der Google API Console:
   1. Rufen Sie die Liste mit den OAuth 2.0-Anmeldedaten auf und wählen Sie Ihren Android-Client aus.
   2. 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:

1. Rufen Sie die Liste mit den OAuth 2.0-Anmeldedaten auf und wählen Sie Ihren Android-Client aus.
2. 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.

Alternative zur Verwendung von benutzerdefinierten URI-Schemas in Chrome-Apps

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

Hinweis:Die Bestätigung der Inhaberschaft von Android-Apps ist derzeit nur für Google Play-Apps verfügbar.

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)

Wichtig:Die Weiterleitungsoption für Loopback-IP-Adressen wurde für die OAuth-Clienttypen Android, Chrome App und iOS verworfen. Eine Anleitung zur Migration zu einer unterstützten Alternative finden Sie in der Migrationsanleitung für Loopback-IP-Adressen.

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.

Hinweis:Weitere Informationen zur Loopback-IP-Adresse finden Sie in der Definition des Parameters redirect_uri. Es ist auch möglich, localhost anstelle der Loopback-IP-Adresse zu verwenden. Diese Konfiguration kann jedoch zu Problemen mit Client-Firewalls führen. Die meisten Firewalls ermöglichen die Loopback-Kommunikation.

Manuell kopieren/einfügen

Wichtig:Die Option zum manuellen Kopieren/Einfügen, auch als Out-of-Band-Weiterleitungsmethode (OOB) bezeichnet, wird nicht mehr unterstützt. Eine Anleitung zur Migration zu einer sicheren Alternative finden Sie im OOB-Migrationsleitfaden.

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.

Hinweis:Die inkrementelle Autorisierung wird für installierte Apps oder Geräte nicht unterstützt.

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.

Wenn Ihre öffentliche Anwendung Bereiche verwendet, die den Zugriff auf bestimmte Nutzerdaten erlauben, muss sie einen Überprüfungsprozess durchlaufen. Wenn beim Testen der Anwendung auf dem Bildschirm die Meldung Nicht überprüfte Anwendung angezeigt wird, müssen Sie eine Überprüfungsanfrage senden, um die Anwendung zu entfernen. Weitere Informationen zu nicht überprüften Anwendungen und Antworten auf häufig gestellte Fragen zur Anwendungsüberprüfung finden Sie in der Hilfe.

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). code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
Einfach	Die Code-Abfrage entspricht dem oben generierten Code-Verifizierer. code_challenge = code_verifier

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 redirect_uri_mismatch angezeigt. In der folgenden Tabelle sehen Sie den entsprechenden redirect_uri-Parameterwert für die jeweilige 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 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. Der Pfad muss mit einem einfachen Schrägstrich beginnen, der sich von normalen HTTP-URLs unterscheidet. Hinweis : Benutzerdefinierte URI-Schemas werden in Chrome-Apps nicht mehr unterstützt und sind unter Android standardmäßig deaktiviert. Weitere Informationen über Alternativen zu benutzerdefinierten Schemas für Android- und Chrome-Apps. Loopback-IP-Adresse http://127.0.0.1:port oder http://[::1]:port Fragen Sie Ihre Plattform nach der entsprechenden Loopback-IP-Adresse ab und starten Sie einen HTTP-Listener mit einem zufällig verfügbaren Port. Ersetzen Sie port durch die tatsächliche Portnummer, die Ihre Anwendung überwacht. Die Unterstützung für die Loopback-IP-Adressweiterleitungsoption in mobilen Apps wurde EINGESTELLT.
response_type	Erforderlich Bestimmt, 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 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_verifier an, die während des Austauschs von Autorisierungscode als serverseitige Identitätsbestätigung verwendet wird. Weitere Informationen finden Sie oben im Abschnitt Code-Challenge erstellen.
code_challenge_method	Empfohlen Gibt an, welche Methode zum Codieren eines code_verifier verwendet wurde, der beim Austausch von Autorisierungscode verwendet wird. Dieser Parameter muss mit dem oben beschriebenen Parameter code_challenge verwendet werden. Der Wert von code_challenge_method wird standardmäßig auf plain gesetzt, wenn er in der Anfrage mit code_challenge nicht vorhanden ist. Für diesen Parameter werden nur die Werte S256 und plain unterstützt.
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 name=value-Paar in der URL-Fragment-ID (#) von redirect_uri senden. 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 redirect_uri erraten werden kann, können Sie mit einem state-Wert die Gewissheit 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 Status des Clients erfasst, können Sie die Antwort validieren, um zusätzlich sicherzustellen, dass die Anfrage und die Antwort vom selben Browser stammen. So wird Schutz vor Angriffen wie websiteübergreifender Anfragefälschung geboten. In der Dokumentation zu OpenID Connect finden Sie ein Beispiel für das Erstellen und Bestätigen eines state-Tokens.
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 sub-ID fest, die der Google-ID des Nutzers entspricht.

Hinweis: Die inkrementelle Autorisierung mit installierten Anwendungen wird nicht unterstützt, da der Client client_secret nicht vertraulich behandeln kann.

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.

Wichtig:Ihre Anwendung sollte beide Tokens an einem sicheren, langlebigen Ort speichern, auf den zwischen verschiedenen Aufrufen der Anwendung zugegriffen werden kann. Mit dem Aktualisierungstoken kann Ihre Anwendung bei Ablauf des Zugriffstokens ein neues Zugriffstoken abrufen. Wenn Ihre Anwendung also das Aktualisierungstoken verliert, muss der Nutzer den OAuth 2.0-Zustimmungsvorgang wiederholen, damit die Anwendung ein neues Aktualisierungstoken abrufen kann.

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

Hinweis: Die Anwendung sollte alle nicht erkannten Felder in der Antwort ignorieren.

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.

Hinweis: Nach einer erfolgreichen Widerrufsantwort kann es einige Zeit dauern, bis der Widerruf vollständig wirksam wird.

Weiterführende Literatur

In der aktuellen IETF-Best Practice OAuth 2.0 für native Apps sind viele der hier dokumentierten Best Practices enthalten.