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

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 begrenzt zulässige Geräteanwendungen.

Rufen Sie zuerst die Anmeldedaten des OAuth 2.0-Clients 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ü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.

Diese Seite bietet einen Überblick über die von Google unterstützten OAuth 2.0-Autorisierungsszenarien und enthält Links zu detaillierteren Inhalten. Weitere Informationen zur Verwendung von OAuth 2.0 für die Authentifizierung finden Sie unter OpenID Connect.

Grundlegende Schritte

Alle Anwendungen haben beim Zugriff auf eine Google API mit OAuth 2.0 ein grundlegendes Muster. Auf übergeordneter Ebene führen Sie fünf Schritte aus:

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

Rufe Google API Console auf, um OAuth 2.0-Anmeldedaten wie eine Client-ID und einen Clientschlüssel abzurufen, die sowohl Google als auch deiner Anwendung bekannt sind. Die Werte variieren je nach Art der Anwendung, die Sie erstellen. Für eine JavaScript-Anwendung ist beispielsweise kein Secret erforderlich, für eine Webserveranwendung hingegen schon.

2. Fordern Sie ein Zugriffstoken vom Google-Autorisierungsserver 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 unterschiedliche Zugriffsebenen gewähren. Der Variablenparameter scope steuert die Ressourcen und Vorgänge, die über ein Zugriffstoken zulässig sind. Während der Anfrage des Zugriffstokens sendet Ihre Anwendung einen oder mehrere Werte im Parameter scope.

Es gibt mehrere Möglichkeiten, diese Anfrage zu stellen. Diese variieren je nach Art der Anwendung, die Sie erstellen. Beispielsweise kann eine JavaScript-Anwendung mithilfe einer Browserweiterleitung an Google ein Zugriffstoken anfordern, während eine Anwendung auf einem Gerät ohne Browser 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 von der Anwendung angefordert werden. Dieser Vorgang wird als Nutzereinwilligung bezeichnet.

Wenn der Nutzer mindestens eine Berechtigung erteilt, 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 von diesem Token erteilt wurden. Wenn der Nutzer die Berechtigung nicht erteilt, gibt der Server einen Fehler zurück.

Es wird allgemein empfohlen, Bereiche inkrementell anzufordern, wenn Zugriff erforderlich ist und nicht im Voraus. Beispielsweise sollte eine App, die das Speichern eines Termins in einem Kalender unterstützen soll, erst dann Zugriff auf Google Kalender anfordern, wenn der Nutzer auf die Schaltfläche „Zum Kalender hinzufügen“ klickt. Weitere Informationen finden Sie unter 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 Funktionen Ihrer Anwendung abhängig vom Zugriff auf eine zugehörige Google API erforderlich sind. Deaktivieren Sie alle Funktionen Ihrer Anwendung ohne Zugriff auf die zugehörige API.

Der in Ihrer Anfrage enthaltene Bereich stimmt möglicherweise nicht mit dem in Ihrer Antwort überein. Dies gilt auch dann, wenn der Nutzer alle angeforderten Bereiche erteilt hat. Informationen zu den für den Zugriff erforderlichen Bereichen finden Sie in der Dokumentation für die einzelnen Google APIs. Eine API kann einem Bereichsumfang mehrere Stringwerte zuordnen und für alle in der Anfrage zulässigen Werte denselben Bereichsstring zurückgeben. Beispiel: Die Google People API gibt möglicherweise den Bereich https://www.googleapis.com/auth/contacts zurück, wenn eine App den 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. Zugriffstoken an eine API senden

Nachdem eine Anwendung ein Zugriffstoken erhalten hat, sendet es das Token an eine Google API in einem HTTP-Autorisierungsheader. Es ist möglich, Tokens als URI-Abfragestringparameter zu senden, aber das wird nicht empfohlen, da URI-Parameter in Protokolldateien enden können, die nicht vollständig sicher sind. Außerdem sollten Sie vermeiden, unnötige URI-Parameternamen zu erstellen.

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

5. Aktualisieren Sie gegebenenfalls das Zugriffstoken.

Zugriffstokens haben nur 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-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 Webserveranwendungen 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, gib an, dass es sich um eine installierte Anwendung handelt. Wähle dann „Android“, „Chrome-App“, „iOS“, „Universal Windows Platform (UWP)“ oder „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 Kontext wird der Clientschlüssel natürlich 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-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.

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 muss, bevor er es 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 damit, dass die Anwendung für einen Autorisierungscode eine Webdienstanfrage an eine Google-URL 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 umfassenderen Eingabefunktionen. Der Nutzer startet einen Browser, ruft die angegebene URL auf, meldet sich an und gibt den Code ein.

In der Zwischenzeit wird von der Anwendung in bestimmten Intervallen eine Google-URL abgefragt. 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 einem Browser an.

Weitere Informationen finden Sie 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. Ebenso kann Ihre Anwendung in Unternehmensszenarien den delegierten Zugriff auf einige Ressourcen anfordern.

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

Die Anmeldedaten eines Dienstkontos, die Sie von Google API Consoleerhalten, umfassen eine eindeutige E-Mail-Adresse, eine eindeutige 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. Ihre Anwendung sendet dann die Tokenanfrage an den Google OAuth 2.0-Autorisierungsserver, 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. Mit diesem Token wird dann ein Google API-Endpunkt aufgerufen. Es ist kein Endnutzer beteiligt.

Weitere Informationen finden Sie in der Dokumentation zu Dienstkonten.

Tokengröße

Die Größe von Tokens kann bis zu den folgenden Limits variieren:

  • Autorisierungscodes: 256 Byte
  • Zugriffstoken: 2.048 Byte
  • Aktualisierungstoken: 512 Byte

Zugriffstoken, die von der Security Token Service API von Google Cloud zurückgegeben werden, sind ähnlich aufgebaut wie OAuth 2.0-Zugriffstokens von Google API, 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. Die Anwendung muss variable Tokengrößen unterstützen.

Ablauf des Aktualisierungstokens

Sie müssen Ihren Code so schreiben, dass die Wahrscheinlichkeit, dass ein gewährtes Aktualisierungstoken nicht mehr funktioniert, vorhersagt. Ein Aktualisierungstoken kann aus einem der folgenden Gründe nicht mehr funktionieren:

Einem Google Cloud Platform-Projekt mit einem OAuth-Zustimmungsbildschirm, der für einen externen Nutzertyp konfiguriert ist und der Veröffentlichungsstatus „Test“ lautet, wird ein Aktualisierungstoken ausgestellt, das in 7 Tagen abläuft. Dies gilt nicht, wenn die einzigen angeforderten OAuth-Bereiche eine Teilmenge von Name, E-Mail-Adresse und Nutzerprofil sind (über die userinfo.email, userinfo.profile, openid-Bereiche oder ihre OpenID Connect-Entsprechungen).

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 ohne Warnung ungültig. Dieses Limit gilt nicht für Dienstkonten.

Die Gesamtzahl der Aktualisierungstokens, die ein Nutzer- oder Dienstkonto für alle Clients haben kann, ist ebenfalls höher. Für die meisten normalen Nutzer wird dieses Limit zwar nicht überschritten, aber es kann sein, dass ein Entwicklerkonto verwendet wird, um eine Implementierung zu testen.

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

Sitzungssteuerungsrichtlinien für Organisationen der Google Cloud Platform (GCP)

Administratoren von GCP-Organisationen fordern möglicherweise eine wiederholte Neuauthentifizierung der Nutzer, wenn sie auf GCP-Ressourcen zugreifen, indem sie die Sitzungssteuerung von Google Cloud verwenden. Diese Richtlinie wirkt sich 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 über eine Sitzungssteuerungsrichtlinie verfügt, geben die API-Aufrufe nach Ablauf der Sitzungsdauer ungefähr so aus:

Gleichermaßen 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 eine Sitzungssteuerungsrichtlinie 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 zur Bereitstellung dieser Funktion für Ihre Kunden finden Sie in diesem Hilfeartikel für Administratoren.

Clientbibliotheken

Die folgenden Clientbibliotheken sind in gängige Frameworks eingebunden, was die Implementierung von OAuth 2.0 vereinfacht. Im Laufe der Zeit werden den Bibliotheken weitere Funktionen hinzugefügt.