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

Google APIs verwenden das OAuth 2.0-Protokoll zur Authentifizierung und Autorisierung. Google unterstützt gängige OAuth 2.0-Szenarien wie beispielsweise Webserver-, clientseitige und installierte Anwendungen sowie Geräte mit begrenzter Eingabe.

Rufen Sie zuerst die Anmeldedaten des OAuth 2.0-Clients von Google API Console ab. Ihre Clientanwendung fordert dann vom Google Authorization Server ein Zugriffstoken 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, eigene Anmeldedaten zu verwenden) können Sie den OAuth 2.0 Playground ausprobieren.

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 greifen beim Zugriff auf eine Google API mit OAuth 2.0 auf ein einfaches Muster zurück. Grundsätzlich führen Sie fünf Schritte aus:

1) OAuth 2.0-Anmeldedaten vom Google API Consoleabrufen.

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. Für eine JavaScript-Anwendung ist beispielsweise kein Secret erforderlich, für eine Webserveranwendung.

Erstellen Sie einen OAuth-Client für die Plattform, auf der Ihre Anwendung ausgeführt wird. Beispiel:

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

Es gibt mehrere Möglichkeiten, diese Anfrage zu stellen. Sie variieren je nach Art der Anwendung, die Sie erstellen. Eine JavaScript-Anwendung fordert beispielsweise ein Zugriffstoken über eine Browserweiterleitung an Google an, während eine Anwendung auf einem Gerät, 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 gewähren möchte, die Ihre Anwendung anfordert. 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) und eine Liste der von diesem Token gewährten Zugriffsbereiche. Wenn der Nutzer die Berechtigung nicht erteilt, gibt der Server einen Fehler zurück.

Im Allgemeinen empfiehlt es sich, Bereiche inkrementell anzufordern, wenn Zugriff erforderlich ist, anstatt im Voraus. Beispiel: Eine App, die das Speichern von Terminen in einem Kalender unterstützt, sollte erst dann Google Kalender-Zugriff anfordern, wenn der Nutzer auf die Schaltfläche „Zum Kalender hinzufügen“ drückt. Weitere Informationen finden Sie unter Inkrementelle Autorisierung.

3. Vom Nutzer gewährte Zugriffsbereiche überprüfen.

Vergleichen Sie die in der Zugriffstoken-Antwort enthaltenen Bereiche mit den Bereichen, die für den Zugriff auf die Funktionen Ihrer Anwendung erforderlich sind, je nach Zugriff auf eine zugehörige Google API. Deaktivieren Sie alle Funktionen Ihrer App, die nicht auf die zugehörige API zugreifen können.

Der in der Anfrage enthaltene Bereich stimmt möglicherweise nicht mit dem in der Antwort enthaltenen Bereich überein, selbst wenn der Nutzer alle angeforderten Bereiche gewährt hat. Informationen zu den für den Zugriff erforderlichen Bereichen finden Sie in der Dokumentation für die einzelnen Google APIs. Eine API kann mehrere Bereichsstringwerte einem einzelnen Zugriffsbereich zuordnen und für alle Werte, die in der Anfrage zulässig sind, denselben Bereichsstring zurückgeben. Beispiel: Die Google People API gibt einen Bereich von https://www.googleapis.com/auth/contacts zurück, wenn eine App einen Nutzer dazu veranlasst, den Bereich von https://www.google.com/m8/feeds/ zu autorisieren. Für die Google People API-Methode people.updateContact ist der gewährte Bereich https://www.googleapis.com/auth/contacts erforderlich.

4. Zugriffstoken an eine API senden

Nachdem eine Anwendung ein Zugriffstoken abgerufen hat, sendet es das Token in einem HTTP-Autorisierungs-Header an eine Google API. Es ist möglich, Tokens als URI-Abfragestringparameter zu senden. Dies wird jedoch nicht empfohlen, da URI-Parameter in Protokolldateien enden können, die nicht vollständig sicher sind. Außerdem empfehlen wir, keine unnötigen URI-Parameternamen 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 ausgegeben wird, wird kein Zugriff auf die Google Kontakte API gewährt. Allerdings können Sie dieses Zugriffstoken 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 Ihre Anwendung über die Lebensdauer eines einzelnen Zugriffstokens hinaus 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 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, 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 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 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 Sie eine Client-ID über Google API Console erstellen, geben Sie an, dass dies eine installierte Anwendung ist. Wählen Sie dann Android, Chrome-App, iOS, Universal Windows Platform (UWP) oder Desktop-Anwendung 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, 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 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 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 zu einer 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 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 Authorization Server, 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 nach einem 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.

Die Anwendung fragt in einem bestimmten Intervall eine Google-URL ab. Nachdem der Nutzer den Zugriff genehmigt hat, enthält die Antwort des Google-Servers 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 an, das einen Browser hat.

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, aber es ist keine Nutzereinwilligung erforderlich. In Unternehmensszenarien kann Ihre Anwendung auch den 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 statt eines einzelnen Endnutzers Ihrer Anwendung gehört. Ihre Anwendung ruft Google APIs im Namen des Dienstkontos auf. Die Nutzereinwilligung ist nicht erforderlich. (In Nicht-Dienstkontoszenarien ruft Ihre Anwendung Google APIs im Namen von Endnutzern auf und die Nutzereinwilligung ist manchmal erforderlich.)

Die Anmeldedaten eines Dienstkontos, die Sie über Google API Consoleabrufen, umfassen eine eindeutige, eindeutige 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. Ihre 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 ein JWT, um ein Token vom Google Authorization Server anzufordern und dann das Token, um einen Google API-Endpunkt aufzurufen. Endnutzer sind nicht beteiligt.

Weitere Informationen finden Sie in der Dienstkontodokumentation.

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

Die von der Security Token Service API von Google Cloud zurückgegebenen Zugriffstokens sind ähnlich aufgebaut mit den OAuth 2.0-Zugriffstokens der 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 Größe von Tokens innerhalb dieser Limits zu ändern. Ihre Anwendung muss Variablen mit unterschiedlichen Größen entsprechend unterstützen.

Ablauf des Aktualisierungstokens

Sie müssen Ihren Code so schreiben, dass die Wahrscheinlichkeit vorhergesagt wird, dass ein bereitgestelltes Aktualisierungstoken nicht mehr funktioniert. Ein Aktualisierungstoken funktioniert aus einem der folgenden Gründe möglicherweise nicht mehr:

Ein Google Cloud Platform-Projekt, in dem ein OAuth-Zustimmungsbildschirm für einen externen Nutzertyp und den Veröffentlichungsstatus „Test“ konfiguriert ist, erhält ein Aktualisierungstoken, das nach 7 Tagen abläuft, es sei denn, die einzigen angeforderten OAuth-Bereiche sind eine Teilmenge des Namens, der E-Mail-Adresse und des Nutzerprofils (über die Bereiche userinfo.email, userinfo.profile, openid oder ihre Entsprechungen in OpenID Connect).

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.

Es gibt auch ein höheres Limit für die Gesamtzahl der Aktualisierungstokens, die ein Nutzerkonto oder Dienstkonto für alle Clients haben kann. Die meisten normalen Nutzer überschreiten dieses Limit nicht, aber ein Entwicklerkonto, das für den Test einer Implementierung verwendet wird, könnte sein.

Wenn du mehrere Programme, Computer oder Geräte autorisieren musst, besteht eine provisorische Lösung darin, die Anzahl der von dir autorisierten Clients auf 15 oder 20 pro Google-Konto zu beschränken. Als Google Workspace-Administrator können Sie zusätzliche Nutzer mit Administratorberechtigungen erstellen und zum Autorisieren einiger Clients verwenden.

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

Administratoren von Google Cloud-Organisationen müssen Nutzer unter Umständen mit dem Google Cloud-Feature zur Sitzungssteuerung während des Zugriffs auf GCP-Ressourcen häufig neu authentifizieren. 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 für einen Nutzer eine Sitzungssteuerungsrichtlinie festgelegt ist, werden bei Ablauf der Sitzungsdauer die API-Aufrufe ähnlich wie bei einem Widerruf des Aktualisierungstokens ausgegeben – der Aufruf schlägt mit dem Fehlertyp invalid_grant fehl. Das Feld error_subtype kann verwendet werden, um zwischen einem widerrufenen Token und einem Fehler aufgrund einer Sitzungssteuerungsrichtlinie zu unterscheiden (z. B. "error_subtype": "invalid_rapt" kann zwischen 1 Stunde und 1 Stunde variieren).

Ebenso dürfen Sie keine Anmeldedaten von Nutzern für die Server-zu-Server-Bereitstellung verwenden oder dafür ermuntern. Wenn Nutzeranmeldedaten auf einem Server für lange andauernde 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 dieses Features unterstützen können, finden Sie in diesem Hilfeartikel für Administratoren.

Clientbibliotheken

Die folgenden Clientbibliotheken werden in beliebte Frameworks eingebunden, die die Implementierung von OAuth 2.0 vereinfachen. Im Laufe der Zeit werden den Bibliotheken weitere Funktionen hinzugefügt.