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 zur Authentifizierung und Autorisierung das OAuth 2.0-Protokoll. Google unterstützt gängige OAuth 2.0-Szenarien, z. B. für Webserver-, clientseitige, installierte und Geräteeingaben mit begrenzter Eingabe.

Rufen Sie zuerst die OAuth 2.0-Clientanmeldedaten aus der Google API Console ab. Dann 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ür eine interaktive Demonstration der Verwendung von OAuth 2.0 mit Google (einschließlich der Option zur Verwendung Ihrer eigenen Client-Anmeldedaten) können Sie mit OAuth 2.0 Playground experimentieren.

Auf dieser Seite erhältst du einen Überblick über die von Google unterstützten OAuth 2.0-Autorisierungsszenarien 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. Grundsätzlich folgen fünf Schritte:

1. Rufen Sie die OAuth 2.0-Anmeldedaten von 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 Werte variieren je nach Art der Anwendung, die Sie erstellen. Eine JavaScript-Anwendung erfordert beispielsweise kein Secret, eine Webserveranwendung jedoch schon.

2. Fordern Sie ein Zugriffstoken vom Google Authorization Server an.

Bevor 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 mehreren APIs unterschiedlichen Zugriffsberechtigungen gewähren. Ein Variablenparameter namens scope steuert die Gruppe von Ressourcen und Vorgängen, die ein Zugriffstoken zulässt. Während der Zugriffstokenanfrage sendet die Anwendung einen oder mehrere Werte im Parameter scope.

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

Einige Anfragen erfordern einen Authentifizierungsschritt, 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, sowie eine Liste der Zugriffsbereiche, die durch dieses Token gewährt werden. Wenn der Nutzer die Berechtigung nicht erteilt, gibt der Server einen Fehler zurück.

Im Allgemeinen empfiehlt es sich, Bereiche schrittweise anzufordern, wenn Zugriff erforderlich ist und nicht im Voraus. Beispiel: Eine App, die das Speichern von Terminen in einem Kalender unterstützen soll, sollte erst dann Google Kalender-Zugriff anfordern, wenn der Nutzer die Schaltfläche „Zum Kalender hinzufügen“ drückt; siehe Inkrementelle Autorisierung.

3. Überprüfen Sie die vom Nutzer gewährten Zugriffsbereiche.

Vergleichen Sie die in der Zugriffstokenantwort enthaltenen Bereiche mit den Bereichen, die für den Zugriff auf die Merkmale und Funktionen Ihrer Anwendung erforderlich sind. Dies hängt vom Zugriff auf eine zugehörige Google API ab. 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 in Ihrer Antwort enthaltenen Bereich überein, auch wenn der Nutzer alle angeforderten Bereiche gewährt hat. Informationen zu den erforderlichen Zugriffsberechtigungen finden Sie in der Dokumentation der einzelnen Google APIs. Eine API kann einem Bereich mit mehreren Zugriffsbereichen Stringwerte zuordnen und für alle in der Anfrage zulässigen Werte denselben Bereichsstring zurückgeben. Beispiel: Die Google People API kann den Bereich https://www.googleapis.com/auth/contacts zurückgeben, wenn eine App den Nutzer https://www.google.com/m8/feeds/ angefordert hat. Die Google People API-Methode people.updateContact erfordert einen zugewiesenen Bereich von https://www.googleapis.com/auth/contacts.

4. Zugriffstoken an eine API senden

Nachdem eine Anwendung ein Zugriffstoken erhalten hat, sendet sie das Token in einem HTTP-Anfrageheader zur HTTP-Autorisierung an eine Google API. Es ist möglich, Tokens als URI-Anfragestringparameter zu senden, dies wird jedoch nicht empfohlen, da URI-Parameter in Protokolldateien landen können, die nicht vollständig sicher sind. Es empfiehlt sich außerdem, REST-Parameternamen nicht unnötig zu erstellen.

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

5. Aktualisieren Sie bei Bedarf das Zugriffstoken.

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

Szenarien

Webserveranwendungen

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

Die Autorisierungssequenz beginnt, wenn Ihre Anwendung einen Browser zu einer Google-URL weiterleitet. Die URL enthält Suchparameter, die die Art des angeforderten Zugriffs angeben. Google übernimmt die Nutzerauthentifizierung, die Sitzungsauswahl und die Nutzereinwilligung. Das Ergebnis ist ein Autorisierungscode, den die Anwendung gegen ein Zugriffstoken und ein Aktualisierungstoken austauschen 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 Authorization Server, empfängt einen Autorisierungscode, tauscht den Code gegen ein Token aus und verwendet das Token, um einen Google API-Endpunkt aufzurufen.

Weitere Informationen findest du unter OAuth 2.0 für Webserver-Anwendungen verwenden.

Installierte Apps

Der Google OAuth 2.0-Endpunkt unterstützt Anwendungen, die auf Geräten wie Computern, Mobilgeräten und Tablets installiert sind. Wenn du eine Client-ID über Google API Console erstellst, musst du angeben, dass es sich um eine installierte Anwendung handelt. Wähle dann als Anwendungstyp „Android“, „Chrome-App“, „iOS“, „Universal Windows Platform (UWP)“ oder „Desktop-App“ 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 Kontext wird der Clientschlüssel offensichtlich nicht als Secret behandelt.

Die Autorisierungssequenz beginnt, wenn Ihre Anwendung einen Browser zu einer Google-URL weiterleitet. Die URL enthält Suchparameter, die die Art des angeforderten Zugriffs angeben. Google übernimmt die Nutzerauthentifizierung, die Sitzungsauswahl und die Nutzereinwilligung. Das Ergebnis ist ein Autorisierungscode, den die Anwendung gegen ein Zugriffstoken und ein Aktualisierungstoken austauschen 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 Authorization Server, empfängt einen Autorisierungscode, tauscht den Code gegen ein Token aus und verwendet das Token, um einen Google API-Endpunkt aufzurufen.

Weitere Informationen findest du unter OAuth 2.0 für installierte Anwendungen verwenden.

Clientseitige (JavaScript-)Anwendungen

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 zu einer Google-URL weiterleitet. Die URL enthält Suchparameter, die die Art des angeforderten Zugriffs angeben. Google übernimmt die Nutzerauthentifizierung, die Sitzungsauswahl und die 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 Authorization Server, empfängt ein Token, validiert das Token und verwendet das Token, um einen Google API-Endpunkt aufzurufen.

Weitere Informationen findest du 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 damit, dass die Anwendung eine Webdienstanfrage an einen Google-URL für einen Autorisierungscode sendet. Die Antwort enthält mehrere Parameter, darunter eine URL und einen Code, den die Anwendung dem Nutzer anzeigt.

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

Außerdem ruft die Anwendung in bestimmten Intervallen eine Google-URL ab. Nachdem 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 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 gegenüber der API ihre eigene Identität nachweisen, es ist jedoch keine Nutzereinwilligung erforderlich. In Unternehmensszenarien kann Ihre Anwendung in ähnlicher Weise einen delegierten Zugriff auf einige Ressourcen anfordern.

Für diese Arten von Server-zu-Server-Interaktionen benötigen Sie ein Dienstkonto. Dies ist ein Konto, das zu Ihrer Anwendung und nicht zu einem bestimmten Endnutzer gehört. Ihre Anwendung ruft Google APIs im Namen des Dienstkontos auf und die Zustimmung des Nutzers ist nicht erforderlich. In Nicht-Dienstkontoszenarien ruft Ihre Anwendung Google APIs im Namen von Endnutzern auf und die Zustimmung des Nutzers ist manchmal erforderlich.

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

Ihre Serveranwendung verwendet ein JWT, um ein Token vom Google Authorization Server anzufordern. Anschließend wird mithilfe des Tokens ein Google API-Endpunkt aufgerufen. Endnutzer sind nicht beteiligt.

Weitere Informationen finden Sie in der Dienstkontodokumentation.

Tokengröße

Tokens können in der Größe bis zu den folgenden Beschränkungen variieren:

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

Die von der Security Token Service API von Google Cloud zurückgegebenen Zugriffstokens sind ähnlich aufgebaut wie die Zugriffstokens der Google API OAuth 2.0, haben aber unterschiedliche Limits für die Tokengröße. 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 variable Tokengrößen entsprechend unterstützen.

Ablauf des Aktualisierungstokens

Sie müssen Ihren Code so schreiben, dass die Wahrscheinlichkeit vorhergeht, dass ein bereitgestelltes 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 wurde sechs Monate lang nicht verwendet.
  • Der Nutzer hat Passwörter geändert und das Aktualisierungstoken enthält Gmail-Bereiche.
  • Das Nutzerkonto hat die maximal zulässige Anzahl von (aktualisierten) Aktualisierungstokens überschritten.
  • Der Nutzer gehört zu einer Google Cloud Platform-Organisation, für die Sitzungsrichtlinien gelten.

Einem Google Cloud Platform-Projekt mit einem für einen externen Nutzertyp konfigurierten OAuth-Zustimmungsbildschirm und dem Veröffentlichungsstatus „Test“ wird ein Aktualisierungstoken ausgestellt, das in 7 Tagen abläuft.

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

Es gibt auch ein höheres Limit für die Gesamtzahl der Aktualisierungstokens, die ein Nutzer- oder Dienstkonto für alle Clients haben kann. Die meisten normalen Nutzer dürfen diese Grenze nicht überschreiten, aber ein Entwicklerkonto, das zum Testen einer Implementierung verwendet wird, kann dies überschreiten.

Wenn du mehrere Programme, Computer oder Geräte autorisieren musst, kannst du das Problem umgehen, indem du die Anzahl der Clients, die du pro Google-Konto autorisierst, auf 15 oder 20 beschränkt. Als Google Workspace-Administrator können Sie zusätzliche Nutzer mit Administratorberechtigungen erstellen und zum Autorisieren einiger Clients verwenden.

Richtlinien zur Sitzungssteuerung für Google Cloud Platform-Organisationen (GCP)

Administratoren von GCP-Organisationen verlangen möglicherweise, dass Nutzer während des Zugriffs auf GCP-Ressourcen wiederholt neu authentifiziert werden. Hierfür wird die Google Cloud-Sitzungssteuerung verwendet. Diese Richtlinie wirkt sich auf den Zugriff auf die Google Cloud Console, das Google Cloud SDK (auch als gcloud CLI bezeichnet) und alle OAuth-Anwendungen von Drittanbietern aus, für die der Cloud Platform-Bereich erforderlich ist. Wenn ein Nutzer eine Sitzungssteuerungsrichtlinie eingerichtet hat, geben Ihre API-Aufrufe nach Ablauf der Sitzungsdauer eine Fehlermeldung aus, wie sie beim Widerrufen des Aktualisierungstokens angezeigt wird. Der Aufruf schlägt mit dem Fehlertyp invalid_token fehl. Der Fehlertyp kann verwendet werden, um zwischen einem widerrufenen Token und einem Fehler aufgrund einer Sitzungssteuerungsrichtlinie zu unterscheiden. Da die Sitzungsdauer sehr begrenzt sein kann (zwischen 1 Stunde und 24 Stunden), muss dieses Szenario ordnungsgemäß gehandhabt werden, indem eine Authentifizierungssitzung neu gestartet wird.

Ebenso dürfen Sie Nutzeranmeldedaten für die Server-zu-Server-Bereitstellung weder nutzen noch deren Verwendung fördern. 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 keine Möglichkeit gibt, den Nutzer nach Ablauf der Sitzungsdauer noch einmal zu authentifizieren.

Weitere Informationen dazu, wie Sie Ihre Kunden bei der Bereitstellung dieser Funktion unterstützen können, finden Sie in diesem Hilfeartikel.

Clientbibliotheken

Die folgenden Clientbibliotheken sind in gängige Frameworks eingebunden, was die Implementierung von OAuth 2.0 vereinfacht. Im Laufe der Zeit kommen weitere Funktionen hinzu.