OAuth 2.0 für mobile und Desktop-Apps

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

OAuth 2.0 ermöglicht Nutzern, bestimmte Daten für eine Anwendung freizugeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Eine Anwendung kann beispielsweise über OAuth 2.0 die Berechtigung zum Abrufen der YouTube-Daten eines Kanals anfordern.

Installierte Apps 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 Autorisierungsablauf ä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 empfiehlt sich möglicherweise Google Log-in für Android oder iOS. Die Google Log-in-Clientbibliotheken verarbeiten die Authentifizierung und Nutzerautorisierung. Sie sind möglicherweise einfacher zu implementieren als das hier beschriebene untergeordnete Protokoll.

Informationen zu Apps auf Geräten, die keinen Systembrowser unterstützen oder eingeschränkte Eingabefunktionen bieten (z. B. Fernseher, Spielekonsolen, Kameras oder Drucker), finden Sie unter OAuth 2.0 für Fernseher und Geräte oder Anmeldung auf Fernsehern und eingeschränkten Eingabegeräten.

Bibliotheken und Beispiele

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

Voraussetzungen

Die APIs für Ihr Projekt aktivieren

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

So aktivieren Sie eine API für Ihr Projekt:

  1. Open the API Library in der Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Auf der Seite „Bibliothek“ kannst du die YouTube Data API suchen und aktivieren. Suchen Sie nach anderen APIs, die Ihre Anwendung verwenden wird, und aktivieren Sie diese ebenfalls.

Anmeldedaten für die Autorisierung erstellen

Anwendungen, die OAuth 2.0 für den Zugriff auf Google APIs verwenden, müssen Anmeldedaten zur Identifizierung gegenüber dem OAuth 2.0-Server von Google haben. In den folgenden Schritten wird erläutert, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann mit den Anmeldedaten auf APIs zugreifen, die Sie für das 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 vom Google-Autorisierungsserver unterstützten Clienttypen und Weiterleitungsmethoden beschrieben. Wähle den für deine Anwendung empfohlenen Clienttyp aus, benenne deinen OAuth-Client und lege die anderen Felder im Formular entsprechend fest.
Android
  1. Wählen Sie als App-Typ 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 Kunden 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 SHA-1-Signaturzertifikat-Fingerabdruck der App-Bereitstellung ein.
    • Wenn deine App die App-Signatur von Google Play verwendet, kopiere den SHA-1-Fingerabdruck von der App-Signaturseite der Play Console.
    • Wenn Sie Ihren eigenen Schlüsselspeicher und Signaturschlüssel verwalten, verwenden Sie das in Java enthaltene Dienstprogramm keytool, um Zertifikatsinformationen in einem visuell lesbaren Format auszugeben. 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 als App-Typ 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 Kunden 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 „General“ (Allgemein) oder im Bereich „Signing & Capabilities“ 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)

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

    1. Öffnen Sie die App Store App auf Ihrem iOS- oder iPadOS-Gerät.
    2. Suchen Sie nach Ihrer App.
    3. Wählen Sie die Schaltfläche Teilen aus (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 zu Ihrem 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 Kunden zu identifizieren.
  3. Geben Sie die 12-stellige Microsoft Store-ID Ihrer Anwendung ein. Sie finden diesen Wert im Microsoft Partnercenter auf der Seite App-Identität im Bereich „App-Verwaltung“.
  4. Klicken Sie auf Erstellen.

Bei UWP-Apps darf das Schema für benutzerdefinierte URIs nicht länger als 39 Zeichen sein.

Benutzerdefiniertes URI-Schema (Android, iOS, UWP)

Benutzerdefinierte URI-Schemas sind eine Form von Deeplinks, bei denen Ihre App über ein benutzerdefiniertes Schema geöffnet wird.

Alternative zur Verwendung von benutzerdefinierten URI-Schemata unter Android

Mit dem Google Log-in for Android SDK, das die OAuth 2.0-Antwort direkt an deine App sendet, ist kein Weiterleitungs-URI erforderlich.

So migrieren Sie 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 eine vollständige Migration zum empfohlenen Google Log-in for Android SDK durchzuführen:

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

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

  1. Aktualisieren Sie Ihren Code, um das Google Sign-In Android SDK zu verwenden:
    1. Prüfen Sie Ihren Code, um zu ermitteln, 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 Beispiel oben. Weitere Informationen zum Format des benutzerdefinierten URI-Schemawerts finden Sie in der Parameterdefinition redirect_uri.
    2. Notieren Sie sich die Anfrageparameter scope und client_id, die Sie zum Konfigurieren des Google Log-in SDK benötigen.
    3. Folge der Anleitung unter Google Log-in in deine Android-App einbinden, um das SDK einzurichten. Sie können den Schritt OAuth 2.0-Client-ID des Back-End-Servers abrufen überspringen, da Sie die im vorherigen Schritt abgerufene client_id wiederverwenden würden.
    4. Folgen Sie der Anleitung zum Aktivieren des serverseitigen API-Zugriffs. Dazu sind folgende Schritte erforderlich:
      1. Verwenden Sie die Methode getServerAuthCode, um einen Authentifizierungscode 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.
  2. Deaktivieren Sie die Unterstützung für benutzerdefinierte Schemas in der Google API Console:
    1. Rufen Sie die Liste der OAuth 2.0-Anmeldedaten auf und wählen Sie Ihren Android-Client aus.
    2. Gehen Sie zum Bereich Erweiterte Einstellungen, entfernen Sie das Häkchen aus dem Kästchen Benutzerdefiniertes URI-Schema aktivieren und klicken Sie auf Speichern, um die Unterstützung für benutzerdefinierte URI-Schemas zu deaktivieren.
Benutzerdefiniertes URI-Schema wird aktiviert
Sollte die empfohlene Alternative für Sie nicht infrage kommen, können Sie benutzerdefinierte URI-Schemata für Ihren Android-Client aktivieren. Gehen Sie dazu so vor:
  1. Rufen Sie die Liste der 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-Schemata in Chrome-Apps

Mit der Chrome Identity API, die die OAuth 2.0-Antwort direkt an die Anwendung sendet, ist kein Weiterleitungs-URI erforderlich.

App-Inhaberschaft bestätigen (Android, Chrome)

Sie können die Inhaberschaft Ihrer App bestätigen, um das Risiko von App-Identitätsdiebstahl zu verringern.

Android

Für den Abschluss des Bestätigungsvorgangs können Sie Ihr Google Play-Entwicklerkonto verwenden, falls Sie eines haben und Ihre App in der Google Play Console registriert ist. Für eine erfolgreiche Bestätigung müssen die folgenden Voraussetzungen erfüllt sein:

  • Sie müssen 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 Sie die Bestätigung durchführen.
  • Du benötigst die Administratorberechtigung für die App in der Google Play Console. Weitere Informationen zur Zugriffsverwaltung in der Google Play Console.

Klicken Sie im Android-Client im Abschnitt App-Inhaberschaft bestätigen auf die Schaltfläche Inhaberschaft bestätigen, um den Bestätigungsvorgang abzuschließen.

Ist die Überprüfung erfolgreich, wird eine entsprechende Benachrichtigung angezeigt. Andernfalls wird eine Fehlermeldung angezeigt.

Um eine fehlgeschlagene Bestätigung zu beheben, versuchen Sie Folgendes:

  • Die App, die Sie bestätigen möchten, muss in der Google Play Console registriert sein.
  • Sie benötigen die Administratorberechtigung für die App in der Google Play Console.
Chrome

Für den Bestätigungsprozess verwenden Sie Ihr Chrome Web Store-Entwicklerkonto. Für eine erfolgreiche Bestätigung müssen folgende Voraussetzungen erfüllt sein:

  • Du musst im Chrome Web Store-Entwickler-Dashboard einen registrierten Artikel mit derselben Artikel-ID wie der OAuth-Client der Chrome-Erweiterung haben, für den du die Verifizierung vornimmst.
  • Du musst Publisher des Chrome Web Store-Artikels sein. Weitere Informationen zur Zugriffsverwaltung im Chrome Web Store-Entwickler-Dashboard.

Klicken Sie im Abschnitt App-Inhaberschaft bestätigen des Clients für Chrome-Erweiterungen auf die Schaltfläche Inhaberschaft bestätigen, um den Bestätigungsprozess abzuschließen.

Hinweis: Warten Sie einige Minuten, bevor Sie den Bestätigungsvorgang abschließen, nachdem Sie Zugriff auf Ihr Konto gewährt haben.

Ist die Überprüfung erfolgreich, wird eine entsprechende Benachrichtigung angezeigt. Andernfalls wird eine Fehlermeldung angezeigt.

Um eine fehlgeschlagene Bestätigung zu beheben, versuchen Sie Folgendes:

  • 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 die Liste deiner Gruppen-Publisher gerade aktualisiert hast, überprüfe, ob die Liste der Gruppen-Publisher-Mitglieder im Chrome Web Store-Entwickler-Dashboard synchronisiert ist. Weitere Informationen zur Synchronisierung der 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 (aber nicht die Universal Windows Platform)
Formularwerte Legen Sie den Anwendungstyp auf Desktop-App fest.

Manuelles 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.

Die YouTube Data API Version 3 nutzt die folgenden Bereiche:

Sucher
https://www.googleapis.com/auth/youtubeYouTube-Konto verwalten
https://www.googleapis.com/auth/youtube.channel-memberships.creatorEine Liste der aktuell aktiven Mitglieder des Kanals, ihre Stufe und ihr Eintrittsdatum abrufen
https://www.googleapis.com/auth/youtube.force-sslIhre YouTube-Videos, -Bewertungen, -Kommentare und -Untertitel ansehen, bearbeiten oder dauerhaft löschen
https://www.googleapis.com/auth/youtube.readonlyYouTube-Konto abrufen
https://www.googleapis.com/auth/youtube.uploadYouTube-Videos verwalten
https://www.googleapis.com/auth/youtubepartnerIhre Inhalte und zugehörigen Content bei YouTube abrufen und verwalten
https://www.googleapis.com/auth/youtubepartner-channel-auditPrivate Informationen aus dem YouTube-Kanal abrufen, die während des Prüfprozesses durch einen YouTube-Partner relevant sind

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

OAuth 2.0-Zugriffstokens abrufen

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

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

Google unterstützt das PKCE-Protokoll (Proof Key for Code Exchange), um den Ablauf der installierten Anwendung sicherer zu machen. Für jede Autorisierungsanfrage wird eine eindeutige Codeprüfung 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.

Die Codeprüfung sollte genügend Entropie haben, damit sich der Wert nicht erraten lässt.

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-Wert der Code-Verifizierer ohne Auffüllung.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
einfach Die Code-Abfrage stimmt mit dem oben generierten Code-Verifizierer überein.
code_challenge = code_verifier

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

Um die Nutzerautorisierung 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 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 App sendet. Für installierte Apps stehen mehrere Weiterleitungsoptionen zur Verfügung. Sie müssen Ihre Autorisierungsanmeldedaten unter Berücksichtigung einer bestimmten Weiterleitungsmethode einrichten.

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, erhalten Sie den Fehler redirect_uri_mismatch.

In der folgenden Tabelle sehen Sie den jeweiligen redirect_uri-Parameterwert für die einzelnen Methoden:

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

oder

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

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

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 für installierte Anwendungen den Parameterwert 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 könnte. 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 ermöglichen sie Nutzern, den Umfang des Zugriffs auf Ihre Anwendung zu steuern. Daher besteht ein umgekehrter Zusammenhang zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, dass die Nutzereinwilligung eingeholt wird.

Die YouTube Data API Version 3 nutzt die folgenden Bereiche:

Sucher
https://www.googleapis.com/auth/youtubeYouTube-Konto verwalten
https://www.googleapis.com/auth/youtube.channel-memberships.creatorEine Liste der aktuell aktiven Mitglieder des Kanals, ihre Stufe und ihr Eintrittsdatum abrufen
https://www.googleapis.com/auth/youtube.force-sslIhre YouTube-Videos, -Bewertungen, -Kommentare und -Untertitel ansehen, bearbeiten oder dauerhaft löschen
https://www.googleapis.com/auth/youtube.readonlyYouTube-Konto abrufen
https://www.googleapis.com/auth/youtube.uploadYouTube-Videos verwalten
https://www.googleapis.com/auth/youtubepartnerIhre Inhalte und zugehörigen Content bei YouTube abrufen und verwalten
https://www.googleapis.com/auth/youtubepartner-channel-auditPrivate Informationen aus dem YouTube-Kanal abrufen, die während des Prüfprozesses durch einen YouTube-Partner relevant sind

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.

code_challenge Empfohlen

Gibt eine codierte code_verifier an, die bei der serverseitigen Identitätsbestätigung beim Austausch des Autorisierungscodes 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 während des Autorisierungscodeaustauschs 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 nicht in der Anfrage mit code_challenge 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 aufrechtzuerhalten. Der Server gibt genau den Wert zurück, den Sie als name=value-Paar in der URL-Fragment-ID (#) von redirect_uri senden, nachdem der Nutzer der Zugriffsanfrage Ihrer Anwendung zugestimmt oder sie abgelehnt hat.

Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung zu leiten, Nonces zu senden und websiteübergreifende Anfragefälschungen zu verhindern. Da die redirect_uri erraten werden kann, lässt sich mit einem state-Wert die Sicherheit erhöhen, dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanfrage ist. Wenn Sie einen zufälligen String generieren oder den Hash eines Cookies oder eines anderen Werts codieren, der den 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 ist sie vor Angriffen wie websiteübergreifender Anfragefälschung geschützt. In der Dokumentation zu OpenID Connect finden Sie ein Beispiel zum Erstellen und Bestätigen eines state-Tokens.

login_hint Optional

Wenn Ihre Anwendung weiß, welcher Nutzer sich authentifizieren möchte, kann sie mit diesem Parameter dem Google-Authentifizierungsserver einen Hinweis geben. 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-Kennung fest, die der Google-ID des Nutzers entspricht.

Beispiele für Autorisierungs-URLs

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

Jede URL fordert Zugriff auf einen Bereich an, der den Zugriff auf die YouTube-Daten des Nutzers ermöglicht.

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

Benutzerdefiniertes URI-Schema

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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.

Deine Anwendung muss in dieser Phase nichts tun, 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

Bei Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google werden möglicherweise nutzerseitige Fehlermeldungen 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 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 explizit Zugriff gewährt wird.

disallowed_useragent

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

Android

Android-Entwicklern kann diese Fehlermeldung beim Öffnen von Autorisierungsanfragen in android.webkit.WebView angezeigt werden. Entwickler sollten stattdessen Android-Bibliotheken wie Google Log-in für 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 Handler für Android-App-Links oder die Standard-Browser-App. Die Bibliothek Benutzerdefinierte Tabs für Android wird ebenfalls unterstützt.

iOS

iOS- und macOS-Entwickler können auf diesen Fehler stoßen, wenn sie Autorisierungsanfragen in WKWebView öffnen. Entwickler sollten stattdessen iOS-Bibliotheken wie Google Log-in für 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 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 universelle Links-Handler als auch die Standard-Browser-App. Auch die Bibliothek SFSafariViewController ist 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 Challenge 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 auftritt, 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. Sehen Sie sich die autorisierten Weiterleitungs-URIs in Google API Console Credentials pagean.

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

Der redirect_uri-Parameter kann sich auf den OAuth-Out-of-Band-Vorgang (OOB) beziehen, der eingestellt wurde und nicht mehr unterstützt wird. Informationen zum Aktualisieren deiner Integration findest du in der Migrationsanleitung.

invalid_request

Bei Ihrer Anfrage ist ein Fehler aufgetreten. 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 Sie, ob für die OAuth-Einbindung eine empfohlene Integrationsmethode verwendet wird
  • Für den Weiterleitungs-URI wird ein benutzerdefiniertes Schema verwendet : Wenn die Fehlermeldung Das benutzerdefinierte URI-Schema wird in Chrome-Apps nicht unterstützt oder Das benutzerdefinierte URI-Schema ist für Ihren Android-Client nicht aktiviert angezeigt wird, verwenden Sie ein benutzerdefiniertes URI-Schema, das in 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 erhält, hängt vom verwendeten Weiterleitungs-URI-Schema ab. Unabhängig vom Schema enthält die Antwort entweder einen Autorisierungscode (code) oder einen Fehler (error). error=access_denied bedeutet beispielsweise, dass der Nutzer die Anfrage abgelehnt hat.

Wenn der Nutzer Zugriff auf die 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 Client-ID aus der API Console Credentials page.
client_secret Der Clientschlüssel aus API Console Credentials page.
code Der Autorisierungscode, der von der ersten 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 die angegebene client_id aufgeführt sind.

Das folgende Snippet zeigt eine Beispielanfrage:

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

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

Google antwortet auf diese Anfrage, indem es ein JSON-Objekt zurückgibt, 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 den access_token gewährten Zugriffsbereiche, ausgedrückt als Liste mit durch Leerzeichen voneinander getrennten Strings, bei denen die Groß- und Kleinschreibung beachtet wird.
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/youtube.force-ssl",
  "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 geben Sie entweder den Abfrageparameter access_token oder den Bearer-Wert eines Authorization-HTTP-Headers an. Wenn möglich, sollte der HTTP-Header verwendet werden, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen kannst du deine Aufrufe von Google APIs mithilfe einer Clientbibliothek einrichten, z. B. beim Aufruf der YouTube Live Streaming API.

Beachte, dass die YouTube Live Streaming API den Vorgang für Dienstkonten nicht unterstützt. Da es keine Möglichkeit gibt, ein Dienstkonto mit einem YouTube-Konto zu verknüpfen, wird beim Autorisieren von Anfragen mit diesem Ablauf der Fehler NoLinkedYouTubeAccount generiert.

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

HTTP GET-Beispiele

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

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Beispiele für curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Alternativ können Sie die Parameteroption des Abfragestrings verwenden:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

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 den Nutzer um Erlaubnis zu bitten (auch wenn der Nutzer nicht anwesend ist), wenn Sie Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.

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

Felder
client_id Die Client-ID aus API Console.
client_secret Der Clientschlüssel, der aus dem API Consoleabgerufen wurde. Die 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 Autorisierungscode-Austausch zurückgegebene Aktualisierungstoken

Das folgende Snippet zeigt eine Beispielanfrage:

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

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

Solange der Nutzer 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"
}

Beachten Sie, dass es Limits für die Anzahl der ausgegebenen Aktualisierungstokens gibt: ein Limit pro Client/Nutzer-Kombination und ein anderes 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 erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Token widerrufen

In manchen Fällen möchte ein Nutzer den Zugriff auf eine App widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen findest du im Supportdokument Website- oder App-Zugriff entfernen im Supportdokument von Drittanbietern.

Apps können den ihr gewährten Zugriff auch programmatisch widerrufen. Der programmatische Widerruf ist wichtig, wenn sich ein Nutzer abmeldet, 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 umfassen, 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 das Token ein Zugriffstoken ist und ein entsprechendes Aktualisierungstoken vorhanden ist, wird auch das Aktualisierungstoken widerrufen.

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

Weiterführende Literatur

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