Verwenden von OAuth 2.0 für den Zugriff auf Google APIs

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Google APIs verwenden das OAuth 2.0-Protokoll für die Authentifizierung und Autorisierung. Google unterstützt gängige OAuth 2.0-Szenarien, z. B. für Webserver-, clientseitige, installierte und eingeschränkte Eingabegeräte.

Rufen Sie zuerst die OAuth 2.0-Clientanmeldedaten von Google API Console ab. Anschließend fordert Ihre Clientanwendung ein Zugriffstoken vom Google Authorization Server an, extrahiert ein Token aus der Antwort und sendet es an die Google API, auf die Sie zugreifen möchten. Führen Sie eine interaktive Demonstration der Verwendung von OAuth 2.0 mit Google (einschließlich der Option zur Verwendung Ihrer eigenen Client-Anmeldedaten) mit dem OAuth 2.0 Playground durch.

Diese Seite bietet einen Überblick über die OAuth 2.0-Autorisierungsszenarien, die Google unterstützt, sowie Links zu ausführlicheren Inhalten. Weitere Informationen zur Verwendung von OAuth 2.0 für die Authentifizierung finden Sie unter OpenID Connect.

Grundlegende Schritte

Alle Anwendungen folgen einem grundlegenden Muster, wenn sie mit OAuth 2.0 auf eine Google API zugreifen. Auf übergeordneter Ebene sind fünf Schritte erforderlich:

1. Rufen Sie OAuth 2.0-Anmeldedaten vom Google API Consoleab.

Rufen Sie die Google API Console auf, um OAuth 2.0-Anmeldedaten wie eine Client-ID und einen Clientschlüssel abzurufen, die Google und Ihrer Anwendung bekannt sind. Die Gruppe von Werten variiert je nach Art der Anwendung, die Sie erstellen. Für eine JavaScript-Anwendung ist beispielsweise kein Secret erforderlich, für eine Webserver-App dagegen schon.

2. Fordern Sie ein Zugriffstoken vom Google-Autorisierungsserver an.

Damit Ihre Anwendung mit einer Google API auf private Daten zugreifen kann, muss sie ein Zugriffstoken abrufen, das Zugriff auf diese API gewährt. Ein einzelnes Zugriffstoken kann verschiedenen APIs unterschiedliche Zugriffsrechte gewähren. Ein Variablenparameter mit dem Namen scope steuert die Gruppe von Ressourcen und Vorgängen, die mit einem Zugriffstoken zugelassen werden. Während der Zugriffstoken-Anfrage sendet Ihre Anwendung einen oder mehrere Werte im Parameter scope.

Es gibt mehrere Möglichkeiten, diese Anfrage zu senden. Sie variieren je nach Art der Anwendung, die Sie erstellen. Eine JavaScript-Anwendung kann beispielsweise ein Zugriffstoken über eine Browserweiterleitung an Google anfordern, während eine Anwendung, die auf einem Gerät installiert ist und kein Browser unterstützt, Webdienstanfragen verwendet.

Für einige Anfragen ist ein Authentifizierungsschritt erforderlich, bei dem sich der Nutzer mit seinem Google-Konto anmeldet. Nach der Anmeldung wird der Nutzer gefragt, ob er eine oder mehrere Berechtigungen erteilen möchte, die deine Anwendung anfordert. Dieser Vorgang wird als Nutzereinwilligung bezeichnet.

Wenn der Nutzer mindestens eine Berechtigung gewährt, sendet der Google-Autorisierungsserver Ihrer Anwendung ein Zugriffstoken oder einen Autorisierungscode, mit dem Ihre Anwendung ein Zugriffstoken abrufen kann, und eine Liste der von diesem Token gewährten Zugriffsbereiche. Wenn der Nutzer die Berechtigung nicht gewährt, gibt der Server einen Fehler zurück.

Es empfiehlt sich, Bereiche inkrementell in Schritten anzufordern, wenn Zugriff erforderlich ist und nicht im Voraus. Beispiel: Apps, die das Speichern von Terminen in einem Kalender unterstützen möchten, sollten Google Kalender erst dann Zugriff gewähren, wenn der Nutzer auf die Schaltfläche „Zum Kalender hinzufügen“ klickt. Siehe Inkrementelle Autorisierung.

3. Vom Nutzer gewährte Zugriffsbereiche untersuchen.

Vergleichen Sie die in der Zugriffstoken-Antwort enthaltenen Bereiche und die Bereiche, die für den Zugriff auf die Features und Funktionen Ihrer Anwendung erforderlich sind, abhängig vom Zugriff auf eine zugehörige Google API. Deaktivieren Sie alle Funktionen Ihrer App ohne Zugriff auf die zugehörige API.

Der in Ihrer Anfrage enthaltene Bereich stimmt möglicherweise nicht mit dem Bereich in Ihrer Antwort überein, auch wenn der Nutzer alle angeforderten Bereiche erteilt hat. Entsprechende Informationen finden Sie in der Dokumentation der einzelnen Google APIs. Eine API kann einem Bereich mit Zugriffsbereichen mehrere Bereichsstringwerte zuordnen und dabei denselben Bereichstring für alle in der Anfrage zulässigen Werte zurückgeben. Beispiel: Die Google People API kann den Bereich https://www.googleapis.com/auth/contacts zurückgeben, wenn eine Anwendung einen Nutzer dazu autorisiert hat, den Bereich https://www.google.com/m8/feeds/ zu autorisieren. Für die Google People API-Methode people.updateContact ist ein gewährter Bereich von https://www.googleapis.com/auth/contacts erforderlich.

4. Das Zugriffstoken an eine API senden.

Nachdem eine Anwendung ein Zugriffstoken abgerufen hat, sendet sie es an eine Google API in einem HTTP Authorization Request Header. Es ist möglich, Tokens als URI-Abfragestringparameter zu senden, wir empfehlen dies jedoch nicht, da URI-Parameter in Protokolldateien landen können, die nicht vollständig sicher sind. Außerdem empfiehlt es sich, REST-Parameternamen nicht zu erstellen.

Zugriffstokens sind nur für die in der scope-Anfrage angegebenen Vorgänge und Ressourcen gültig. Wenn beispielsweise ein Zugriffstoken für die Google Calendar API ausgestellt wird, wird kein Zugriff auf die Google Contacts API gewährt. Für ähnliche Vorgänge können Sie das Zugriffstoken jedoch mehrmals an die Google Calendar API senden.

5. Aktualisieren Sie das Zugriffstoken, falls erforderlich.

Zugriffstokens haben eine begrenzte Lebensdauer. Wenn Ihre Anwendung über die Lebensdauer eines einzelnen Zugriffstokens hinweg Zugriff auf eine Google API benötigt, kann ein Aktualisierungstoken abgerufen werden. Mit einem Aktualisierungstoken kann Ihre Anwendung neue Zugriffstokens abrufen.

Szenarien

Webserveranwendungen

Der Google OAuth 2.0-Endpunkt unterstützt Webserver-Anwendungen, die Sprachen und Frameworks wie PHP, Java, Python, Ruby und ASP.NET verwenden.

Die Autorisierungssequenz beginnt, wenn Ihre Anwendung einen Browser an eine Google-URL weiterleitet. Die URL enthält Suchparameter, die die Art der angeforderten Zugriff angeben. Google übernimmt die Nutzerauthentifizierung, Sitzungsauswahl und Nutzereinwilligung. Das Ergebnis ist ein Autorisierungscode, den die Anwendung gegen ein Zugriffstoken und ein Aktualisierungstoken eintauschen kann.

Die Anwendung sollte das Aktualisierungstoken für die zukünftige Verwendung speichern und das Zugriffstoken für den Zugriff auf eine Google API verwenden. Sobald das Zugriffstoken abläuft, verwendet die Anwendung das Aktualisierungstoken, um ein neues zu erhalten.

Ihre Anwendung sendet eine Tokenanfrage an den Google-Autorisierungsserver, empfängt einen Autorisierungscode, tauscht den Code gegen ein Token aus und verwendet das Token, um einen Google API-Endpunkt aufzurufen.

Weitere Informationen finden Sie unter Einsatz von OAuth 2.0 für Webserveranwendungen.

Installierte Apps

Der Google OAuth 2.0-Endpunkt unterstützt Anwendungen, die auf Geräten wie Computern, Mobilgeräten und Tablets installiert sind. Wenn Sie eine Client-ID über den Google API Console erstellen, geben Sie an, dass es sich um eine installierte Anwendung handelt. Wählen Sie dann Android, die Chrome-App, iOS, die Universal Windows Platform (UWP) oder die Desktop-App als Anwendungstyp aus.

Der Prozess führt zu einer Client-ID und in einigen Fällen zu einem Clientschlüssel, den Sie in den Quellcode Ihrer Anwendung einbetten. In diesem Zusammenhang wird der Clientschlüssel nicht als Secret behandelt.

Die Autorisierungssequenz beginnt, wenn Ihre Anwendung einen Browser an eine Google-URL weiterleitet. Die URL enthält Suchparameter, die die Art der angeforderten Zugriff angeben. Google übernimmt die Nutzerauthentifizierung, Sitzungsauswahl und Nutzereinwilligung. Das Ergebnis ist ein Autorisierungscode, den die Anwendung gegen ein Zugriffstoken und ein Aktualisierungstoken eintauschen kann.

Die Anwendung sollte das Aktualisierungstoken für die zukünftige Verwendung speichern und das Zugriffstoken für den Zugriff auf eine Google API verwenden. Sobald das Zugriffstoken abläuft, verwendet die Anwendung das Aktualisierungstoken, um ein neues zu erhalten.

Ihre Anwendung sendet eine Tokenanfrage an den Google-Autorisierungsserver, empfängt einen Autorisierungscode, tauscht den Code gegen ein Token aus und verwendet das Token, um einen Google API-Endpunkt aufzurufen.

Weitere Informationen finden Sie unter OAuth 2.0 für installierte Anwendungen verwenden.

Clientseitige Anwendungen (JavaScript)

Der Google OAuth 2.0-Endpunkt unterstützt JavaScript-Anwendungen, die in einem Browser ausgeführt werden.

Die Autorisierungssequenz beginnt, wenn Ihre Anwendung einen Browser an eine Google-URL weiterleitet. Die URL enthält Suchparameter, die die Art der angeforderten Zugriff angeben. Google übernimmt die Nutzerauthentifizierung, Sitzungsauswahl und Nutzereinwilligung.

Das Ergebnis ist ein Zugriffstoken, das der Client validieren sollte, bevor er in eine Google API-Anfrage aufgenommen wird. Wenn das Token abläuft, wiederholt die Anwendung den Vorgang.

Ihre JS-Anwendung sendet eine Tokenanfrage an den Google-Autorisierungsserver, empfängt ein Token, validiert das Token und verwendet das Token, um einen Google API-Endpunkt aufzurufen.

Weitere Informationen finden Sie unter OAuth 2.0 für clientseitige Anwendungen verwenden.

Anwendungen auf Geräten mit begrenzter Eingabe

Der Google OAuth 2.0-Endpunkt unterstützt Anwendungen, die auf Geräten mit begrenzter Eingabe wie Spielekonsolen, Videokameras und Druckern ausgeführt werden.

Die Autorisierungssequenz beginnt mit der Anwendung, die eine Webdienstanfrage an eine Google-URL nach einem Autorisierungscode sendet. Die Antwort enthält mehrere Parameter, einschließlich einer URL und eines Codes, den die Anwendung dem Nutzer anzeigt.

Der Nutzer erhält die URL und den Code vom Gerät und wechselt dann zu einem anderen Gerät oder Computer mit umfangreicheren Eingabemöglichkeiten. Der Nutzer startet einen Browser, ruft die angegebene URL auf, meldet sich an und gibt den Code ein.

In der Zwischenzeit fragt die Anwendung eine Google-URL in einem festgelegten Intervall ab. Sobald der Nutzer den Zugriff genehmigt hat, enthält die Antwort vom Google-Server ein Zugriffstoken und ein Aktualisierungstoken. Die Anwendung sollte das Aktualisierungstoken für die zukünftige Verwendung speichern und das Zugriffstoken für den Zugriff auf eine Google API verwenden. Sobald das Zugriffstoken abläuft, verwendet die Anwendung das Aktualisierungstoken, um ein neues zu erhalten.

Der Nutzer meldet sich auf einem separaten Gerät mit einem Browser an.

Weitere Informationen findest du unter OAuth 2.0 für Geräte verwenden.

Dienstkonten

Google APIs wie die Prediction API und Google Cloud Storage können im Namen Ihrer Anwendung handeln, ohne auf Nutzerinformationen zuzugreifen. In diesen Fällen muss Ihre Anwendung der API ihre eigene Identität nachweisen, es ist jedoch keine Nutzereinwilligung erforderlich. Außerdem kann Ihre Anwendung in Unternehmensszenarien delegierten Zugriff auf einige Ressourcen anfordern.

Für diese Arten von Server-zu-Server-Interaktionen benötigen Sie ein Dienstkonto. Das ist ein Konto, das zu Ihrer Anwendung gehört, nicht zu einem einzelnen Endnutzer. Ihre Anwendung ruft Google APIs im Namen des Dienstkontos auf und die Nutzereinwilligung ist nicht erforderlich. In Szenarien ohne Dienstkonto ruft Ihre Anwendung Google APIs im Namen von Endnutzern auf und die Einwilligung der Nutzer ist manchmal erforderlich.

Die Anmeldedaten für ein Dienstkonto, die Sie von Google API Consoleabrufen, enthalten eine eindeutige E-Mail-Adresse, eine eindeutige Client-ID und mindestens ein Schlüsselpaar aus öffentlichem und privatem Schlüssel. Verwenden Sie die Client-ID und einen privaten Schlüssel, um ein signiertes JWT zu erstellen und eine Zugriffstokenanfrage im richtigen Format zu erstellen. Die Anwendung sendet die Tokenanfrage dann an den Google OAuth 2.0-Autorisierungsserver, der ein Zugriffstoken zurückgibt. Die Anwendung verwendet das Token, um auf eine Google API zuzugreifen. Wenn das Token abläuft, wiederholt die Anwendung den Vorgang.

Ihre Serveranwendung verwendet dann ein JWT, um ein Token vom Google-Autorisierungsserver anzufordern. Anschließend wird das Token mit einem Google API-Endpunkt aufgerufen. Ein Endnutzer ist nicht beteiligt.

Weitere Informationen finden Sie in der Dokumentation zu Dienstkonten.

Tokengröße

Tokens können in der Größe bis zu den folgenden Limits variieren:

  • Autorisierungscodes: 256 Byte
  • Zugriffstokens: 2.048 Byte
  • Aktualisierungstokens: 512 Byte

Von Google Cloud zurückgegebene Zugriffstokens Security Token Service API sind ähnlich aufgebaut wie OAuth API 2.0-Zugriffstokens, haben aber unterschiedliche Größenbeschränkungen. Weitere Informationen finden Sie in der API-Dokumentation.

Google behält sich das Recht vor, die Tokengröße innerhalb dieser Limits zu ändern, und Ihre Anwendung muss entsprechend Variablengrößen unterstützen.

Ablauf des Aktualisierungstokens

Sie müssen Code schreiben, um zu erwarten, dass ein zugewiesenes Aktualisierungstoken nicht mehr funktioniert. Ein Aktualisierungstoken kann aus einem der folgenden Gründe nicht mehr funktionieren:

  • Der Nutzer hat den Zugriff Ihrer App widerrufen.
  • Das Aktualisierungstoken wird seit sechs Monaten nicht mehr verwendet.
  • Der Nutzer hat Passwörter geändert und das Aktualisierungstoken enthält Gmail-Bereiche.
  • Das Nutzerkonto hat die maximale Anzahl gewährter (Live-)Aktualisierungstokens überschritten.
  • Der Nutzer gehört zu einer Google Cloud Platform-Organisation, für die Richtlinien zur Sitzungssteuerung gelten.

Ein Google Cloud Platform-Projekt mit einem OAuth-Zustimmungsbildschirm, der für einen externen Nutzertyp konfiguriert ist und für den der Veröffentlichungsstatus „Test“ angezeigt wird, erhält ein Aktualisierungstoken, das nach 7 Tagen abläuft.

Derzeit gibt es ein Limit von 50 Aktualisierungstokens pro Google-Konto pro OAuth 2.0-Client-ID. Wenn das Limit erreicht ist, wird durch das Erstellen eines neuen Aktualisierungstokens das älteste Aktualisierungstoken automatisch ohne Warnung ungültig. Dieses Limit gilt nicht für Dienstkonten.

Außerdem gibt es eine Obergrenze für die Gesamtzahl der Aktualisierungstokens, die ein Nutzer- oder Dienstkonto für alle Clients haben kann. Die meisten normalen Nutzer werden diese Grenze nicht überschreiten. Es kann aber sein, dass ein Entwicklerkonto zum Testen einer Implementierung verwendet wird.

Wenn Sie mehrere Programme, Maschinen oder Geräte autorisieren müssen, besteht eine Behelfslösung darin, die Anzahl der Clients, die Sie pro Google-Konto autorisieren, auf 15 oder 20 zu beschränken. Als Google Workspace-Administrator können Sie zusätzliche Nutzer mit Administratorberechtigungen erstellen und einige der Clients autorisieren.

Umgang mit Richtlinien für die Sitzungssteuerung für Organisationen der Google Cloud Platform (GCP)

Administratoren von GCP-Organisationen erfordern möglicherweise eine wiederholte Authentifizierung der Nutzer, während sie auf GCP-Ressourcen zugreifen, indem sie die Sitzungssteuerung für Google Cloud verwenden. Diese Richtlinie wirkt sich auf den Zugriff auf die Google Cloud Console, das Google Cloud SDK (auch als gcloud-Befehlszeile bezeichnet) und alle OAuth-Anwendungen von Drittanbietern aus, die den Cloud Platform-Bereich erfordern. Wenn für einen Nutzer eine Richtlinie zur Sitzungssteuerung eingerichtet ist, werden nach Ablauf der Sitzungsdauer die API-Aufrufe ähnlich wie beim Widerrufen des Aktualisierungstokens ausgegeben. Der Aufruf schlägt mit dem Fehlertyp invalid_token fehl. Der Unterfehlertyp kann verwendet werden, um zwischen einem widerrufenen Token und einem Fehler aufgrund einer Sitzungssteuerungsrichtlinie zu unterscheiden. Da die Sitzungsdauer sehr kurz sein kann (zwischen 1 Stunde und 24 Stunden), müssen Sie eine Authentifizierungssitzung neu starten.

Außerdem dürfen Sie Nutzeranmeldedaten für die Server-zu-Server-Bereitstellung weder nutzen noch dazu ermutigen. Wenn Nutzeranmeldedaten auf einem Server für lange laufende Jobs oder Vorgänge bereitgestellt werden und ein Kunde Sitzungssteuerungsrichtlinien auf diese Nutzer anwendet, schlägt die Serveranwendung fehl. Da es nicht möglich ist, den Nutzer nach Ablauf der Sitzung neu zu authentifizieren.

Weitere Informationen zur Bereitstellung dieser Funktion für Ihre Kunden finden Sie in diesem Hilfeartikel.

Clientbibliotheken

Die folgenden Clientbibliotheken lassen sich in beliebte Frameworks einbinden, was die Implementierung von OAuth 2.0 vereinfacht. Im Laufe der Zeit kommen dann weitere Funktionen hinzu.