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 oder Geräteanwendungen mit begrenzter Eingabe.

Rufe zuerst die Anmeldedaten des OAuth 2.0-Clients von 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. Experimentieren Sie mit OAuth 2.0 Playground, um eine interaktive Demonstration der Verwendung von OAuth 2.0 mit Google (einschließlich der Option zur Verwendung Ihrer eigenen Client-Anmeldedaten) zu erhalten.

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

Grundlegende Schritte

Beim Zugriff auf eine Google API mit OAuth 2.0 folgen alle Anwendungen einem grundlegenden Muster. Grundsätzlich führen Sie fünf Schritte aus:

1. Rufen Sie OAuth 2.0-Anmeldedaten aus dem Google API Consoleab.

Rufe die 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 Gruppe von Werten variiert je nach Art der Anwendung, die Sie erstellen. Beispielsweise ist für eine JavaScript-Anwendung kein Secret erforderlich, für eine Webserveranwendung jedoch schon.

Sie müssen einen OAuth-Client erstellen, der für die Plattform geeignet ist, auf der Ihre Anwendung ausgeführt wird. Beispiel:

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 den Zugriff auf diese API gewährt. Ein einzelnes Zugriffstoken kann mehreren APIs unterschiedliche Zugriffsebenen gewähren. Über den Variablenparameter scope werden die Ressourcen und Vorgänge gesteuert, die ein Zugriffstoken zulässt. Während der Anforderung des Zugriffstokens sendet Ihre Anwendung einen oder mehrere Werte im Parameter scope.

Es gibt mehrere Möglichkeiten, diese Anfrage zu stellen, die je nach Art der Anwendung, die Sie erstellen, variieren. Eine JavaScript-Anwendung kann beispielsweise ein Zugriffstoken über eine Browserweiterleitung an Google anfordern, während eine Anwendung, die auf einem Gerät ohne 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 einer oder mehreren von Ihrer Anwendung angeforderten Berechtigungen zustimmen möchte. Dieser Vorgang wird als Nutzereinwilligung bezeichnet.

Wenn der Nutzer mindestens eine Berechtigung erteilt, sendet der Google-Autorisierungsserver deiner Anwendung ein Zugriffstoken (oder einen Autorisierungscode, mit dem deine Anwendung ein Zugriffstoken abrufen kann) und eine Liste der durch dieses Token gewährten Zugriffsbereiche. Wenn der Nutzer die Berechtigung nicht gewährt, gibt der Server einen Fehler zurück.

Im Allgemeinen empfiehlt es sich, Bereiche nur dann inkrementell anzufordern, wenn Zugriff erforderlich ist, und nicht im Voraus. Beispielsweise sollte eine Anwendung, die das Speichern von Terminen in einem Kalender unterstützen soll, erst dann den Zugriff auf Google Kalender anfordern, wenn der Nutzer auf die Schaltfläche „Zum Kalender hinzufügen“ drückt. Weitere Informationen findest du unter Inkrementelle Autorisierung.

3. Prüfen Sie den vom Nutzer gewährten Zugriff.

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

Der in Ihrer Anfrage enthaltene Bereich stimmt möglicherweise nicht mit dem Bereich in Ihrer Antwort überein, auch wenn der Nutzer alle angeforderten Bereiche gewährt hat. In der Dokumentation der einzelnen Google APIs finden Sie die Bereiche, die für den Zugriff erforderlich sind. Eine API kann mehrere Bereichsstringwerte einem einzelnen Zugriffsbereich zuordnen und so 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 einen Nutzer zum Autorisieren des Bereichs https://www.google.com/m8/feeds/ anfordert. Für die Google People API-Methode people.updateContact ist der zugewiesene Bereich https://www.googleapis.com/auth/contacts erforderlich.

4. Zugriffstoken an eine API senden

Nachdem eine Anwendung ein Zugriffstoken abgerufen hat, sendet sie das Token in einem HTTP-Autorisierungs-Anfrageheader an eine Google API. Es ist möglich, Tokens als URI-Abfragestringparameter zu senden. Dies wird jedoch nicht empfohlen, da URI-Parameter in Logdateien enden können, die nicht vollständig sicher sind. Außerdem empfiehlt es sich, keine unnötigen URI-Parameternamen zu erstellen.

Zugriffstokens sind nur für die Vorgänge und Ressourcen gültig, die in der scope der Tokenanfrage beschrieben werden. Wenn beispielsweise ein Zugriffstoken für die Google Calendar API ausgestellt wird, gewährt es keinen Zugriff auf die Google Contacts API. Sie können das Zugriffstoken jedoch für ähnliche Vorgänge 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 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, Go, 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 des angeforderten Zugriffs angeben. Google übernimmt die Nutzerauthentifizierung, Sitzungsauswahl und 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 abgelaufen ist, ruft die Anwendung mithilfe des Aktualisierungstokens ein neues ab.

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 Sie eine Client-ID über Google API Console erstellen, geben Sie an, dass es sich um eine installierte Anwendung handelt. Wählen Sie dann als Anwendungstyp Android, Chrome-App, iOS, Universal Windows Platform (UWP) oder Desktop-App aus.

Der Vorgang 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 an eine Google-URL weiterleitet. Die URL enthält Suchparameter, die die Art des angeforderten Zugriffs angeben. Google übernimmt die Nutzerauthentifizierung, Sitzungsauswahl und 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 abgelaufen ist, ruft die Anwendung mithilfe des Aktualisierungstokens ein neues ab.

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 des angeforderten Zugriffs angeben. Google übernimmt die Nutzerauthentifizierung, Sitzungsauswahl und Nutzereinwilligung.

Das Ergebnis ist ein Zugriffstoken, das der Client validieren sollte, bevor 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 eine Webdienstanfrage an eine 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 umfassenderen Eingabefunktionen. Der Nutzer startet einen Browser, ruft die angegebene URL auf, meldet sich an und gibt den Code ein.

Währenddessen fragt die Anwendung eine Google-URL in einem bestimmten Intervall 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 abgelaufen ist, verwendet die Anwendung das Aktualisierungstoken, um ein neues abzurufen.

Der Nutzer meldet sich auf einem separaten Gerät mit 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 agieren, ohne auf Nutzerinformationen zuzugreifen. In diesen Fällen muss die Anwendung ihre eigene Identität gegenüber der API nachweisen. Es ist jedoch keine Nutzereinwilligung erforderlich. Ebenso 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. Dieses Konto gehört zu Ihrer Anwendung und nicht zu einem einzelnen Endnutzer. Ihre Anwendung ruft Google APIs im Namen des Dienstkontos auf und die Einwilligung des Nutzers ist nicht erforderlich. In Szenarien ohne Dienstkonto ruft Ihre Anwendung Google APIs im Namen von Endnutzern auf und manchmal ist die Einwilligung des Nutzers erforderlich.

Die Anmeldedaten eines Dienstkontos, die Sie von Google API Consoleerhalten, umfassen eine eindeutige generierte E-Mail-Adresse, eine Client-ID und mindestens ein Paar aus öffentlichem und privatem Schlüssel. Mit der Client-ID und einem privaten Schlüssel erstellen Sie ein signiertes JWT und eine Zugriffstokenanfrage im entsprechenden Format. Die 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.

Deine Serveranwendung fordert mithilfe eines JWT ein Token vom Google Authorization Server an und ruft dann mit dem Token einen Google API-Endpunkt auf. Es sind keine Endnutzer beteiligt.

Weitere Informationen finden Sie in der Dokumentation zu Dienstkonten.

Tokengröße

Die Größe von Tokens kann bis zu den folgenden Beschränkungen variieren:

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

Zugriffstokens, die von der Security Token Service API von Google Cloud zurückgegeben werden, sind ähnlich strukturiert wie die OAuth 2.0-Zugriffstokens der Google API, haben aber unterschiedliche Größenbeschränkungen für Tokens. Weitere Informationen findest du in der API-Dokumentation.

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

Ablauf des Aktualisierungstokens

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

Ein Google Cloud Platform-Projekt mit einem für einen externen Nutzertyp konfigurierten OAuth-Zustimmungsbildschirm und dem Veröffentlichungsstatus „Test“ erhält ein Aktualisierungstoken, das 7 Tage abläuft, es sei denn, die einzigen angeforderten OAuth-Bereiche sind eine Teilmenge von Name, E-Mail-Adresse und Nutzerprofil (über die userinfo.email, userinfo.profile, openid-Bereiche oder deren OpenID Connect-Entsprechungen).

Derzeit gilt ein Limit von 100 Aktualisierungstokens pro Google-Konto und OAuth 2.0-Client-ID. Wenn das Limit erreicht ist, wird beim Erstellen eines neuen Aktualisierungstokens automatisch das älteste Aktualisierungstoken ohne Warnung 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 auf allen Clients haben kann. Die meisten normalen Nutzer überschreiten dieses Limit nicht, aber es kann das Entwicklerkonto zum Testen einer Implementierung sein.

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

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

Administratoren von GCP-Organisationen müssen Nutzer möglicherweise mithilfe der Google Cloud-Funktion zur Sitzungssteuerung, wenn sie auf GCP-Ressourcen zugreifen, regelmäßig neu authentifizieren. Diese Richtlinie wirkt sich auf den Zugriff auf die Google Cloud Console, das Google Cloud SDK (auch gcloud CLI) und alle OAuth-Anwendungen von Drittanbietern aus, die den Cloud Platform-Bereich erfordern. Wenn für einen Nutzer eine Sitzungssteuerungsrichtlinie festgelegt ist, werden nach Ablauf der Sitzungsdauer Ihre API-Aufrufe ähnlich wie bei einem Widerruf des Aktualisierungstokens fehlschlagen. Der Aufruf schlägt mit dem Fehlertyp invalid_grant fehl. Anhand des Felds error_subtype kann zwischen einem Token und einem Fehler aufgrund einer Sitzungssteuerungsrichtlinie (z. B. "error_subtype": "invalid_rapt") unterschieden werden. Bei einer Sitzung kann eine Sitzungsdauer von 2 Stunden bis zu einer Stunde begrenzt sein. Die Authentifizierung kann zwischen 1 Stunde und 4 Stunden dauern.

Ebenso dürfen Sie keine Nutzeranmeldedaten für die Server-zu-Server-Bereitstellung verwenden oder deren Verwendung fördern. Wenn für lang andauernde Jobs oder Vorgänge Nutzeranmeldedaten auf einem Server bereitgestellt werden und ein Kunde Richtlinien zur Sitzungssteuerung auf solche Nutzer anwendet, schlägt die Serveranwendung fehl, da nach Ablauf der Sitzungsdauer nicht wieder der Nutzer authentifiziert werden kann.

Weitere Informationen dazu, wie Sie Ihre Kunden bei der Bereitstellung dieses Features unterstützen können, finden Sie in diesem Hilfeartikel speziell für Administratoren.

Clientbibliotheken

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