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

Rufe 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. Wenn du an einer interaktiven Demonstration der Verwendung von OAuth 2.0 mit Google (einschlie�lich der Option zur Verwendung deiner eigenen Clientanmeldedaten) teilnehmen m�chtest, kannst du mit dem OAuth 2.0 Playground experimentieren.

Auf dieser Seite erhalten Sie einen �berblick �ber die von Google unterst�tzten OAuth 2.0-Autorisierungsszenarien sowie Links zu weiterf�hrenden Inhalten. Details zur Verwendung von OAuth 2.0 zur 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 f�hren Sie f�nf Schritte aus:

1. Rufe OAuth 2.0-Anmeldedaten aus dem Google API Consoleab.

Rufen Sie die Google API Console auf, um OAuth 2.0-Anmeldedaten wie eine Client-ID und einen Clientschl�ssel zu erhalten, die sowohl Google als auch Ihrer Anwendung bekannt sind. Die Gruppe von Werten variiert je nach Art der Anwendung, die Sie erstellen. Beispielsweise ist bei einer JavaScript-Anwendung kein Secret erforderlich, bei einer Webserveranwendung dagegen.

Du musst einen OAuth-Client erstellen, der f�r die Plattform geeignet ist, auf der deine Anwendung ausgef�hrt wird. Beispiel:

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

Bevor Ihre Anwendung mithilfe 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. Über den Variablenparameter scope werden die Ressourcen und Vorgänge gesteuert, 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, die sich je nach Art der Anwendung, die Sie erstellen, unterscheiden. Beispielsweise kann eine JavaScript-Anwendung ein Zugriffstoken mithilfe einer Browserweiterleitung an Google anfordern, während eine auf einem Gerät ohne Browser installierte Anwendung 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 von Ihrer Anwendung angeforderte Berechtigungen erteilen möchte. Dieser Vorgang wird als Nutzereinwilligung bezeichnet.

Wenn der Nutzer mindestens eine Berechtigung gewährt, 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 inkrementell anzufordern, wenn Zugriff erforderlich ist, und nicht im Voraus. Beispiel: Eine App, die das Speichern von Terminen in einem Kalender unterstützen möchte, sollte erst dann den Zugriff auf Google Kalender anfordern, wenn der Nutzer auf die Schaltfläche „Zum Kalender hinzufügen“ drückt; siehe Inkrementelle Autorisierung.

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

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. Informationen zu den für den Zugriff erforderlichen Bereichen finden Sie in der Dokumentation der einzelnen Google APIs. Eine API kann mehrere Stringwerte für den Bereich einem einzelnen Zugriffsbereich zuordnen und so 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 einen Nutzer zum Autorisieren des Bereichs https://www.google.com/m8/feeds/ anfordert. Für die Google People API-Methode people.updateContact ist der Zugriffsbereich https://www.googleapis.com/auth/contacts erforderlich.

4. Senden Sie das Zugriffstoken an eine API.

Nachdem eine Anwendung ein Zugriffstoken abgerufen hat, sendet sie das Token in einem Header der HTTP-Autorisierungsanfrage an eine Google API. Es ist m�glich, Tokens als URI-Abfragestringparameter zu senden. Wir raten jedoch davon ab, da URI-Parameter in Protokolldateien landen 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 unter scope der Tokenanfrage beschrieben werden. Wenn beispielsweise ein Zugriffstoken f�r die Google Kalender API ausgegeben wird, wird damit kein Zugriff auf die Google Contacts API gew�hrt. Sie k�nnen das Zugriffstoken jedoch f�r �hnliche Vorg�nge mehrmals an die Google Kalender 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 zu einer Google-URL weiterleitet. Die URL enth�lt Abfrageparameter, 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. Nach Ablauf des Zugriffstokens 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 ruft mithilfe des Tokens einen Google API-Endpunkt auf.

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 die 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“, „Universelle Windows-Plattform“ (UWP) oder „Desktop“ aus.

Bei diesem Vorgang werden eine Client-ID und in einigen Fällen ein Clientschlüssel erzeugt, 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 Abfrageparameter, 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. Nach Ablauf des Zugriffstokens 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 ruft mithilfe des Tokens einen Google API-Endpunkt auf.

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 zu einer Google-URL weiterleitet. Die URL enthält Abfrageparameter, 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 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 ruft mithilfe des Tokens einen Google API-Endpunkt auf.

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 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 anderen Gerät oder Computer mit umfassenderen Eingabemöglichkeiten. Der Nutzer startet einen Browser, ruft die angegebene URL auf, meldet sich an und gibt den Code ein.

Unterdessen 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. Nach Ablauf des Zugriffstokens ruft die Anwendung mithilfe des Aktualisierungstokens ein neues ab.

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 Ihre Anwendung gegen�ber der API ihre eigene Identit�t nachweisen. Es ist jedoch keine Nutzereinwilligung erforderlich. In Unternehmensszenarien kann Ihre Anwendung auch 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 bestimmten 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 manchmal ist die Einwilligung des Nutzers erforderlich.)

Die Anmeldedaten eines Dienstkontos, die Sie im Google API Consoleabrufen, 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 Zugriffstoken-Anfrage im entsprechenden Format. Deine 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 verwendet ein JWT, um ein Token vom Google-Autorisierungsserver anzufordern, 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 Zugriffstokens für OAuth 2.0 der Google API, haben aber unterschiedliche Größenbeschränkungen für Tokens. Weitere Informationen finden Sie in der API-Dokumentation.

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

Ablauf des Aktualisierungstokens

Schreiben Sie Ihren Code so, dass möglich ist, dass ein gewährtes Aktualisierungstoken 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 gültig ist. Eine Ausnahme bildet der Teil, der nur einen Teil des Namens, der E-Mail-Adresse und des Nutzerprofils (über die userinfo.email, userinfo.profile, openid-Bereiche oder deren OpenID Connect-Entsprechungen) angefordert hat.

Derzeit gilt ein Limit von 100 Aktualisierungstokens pro Google-Konto und 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.

Au�erdem gibt es 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 jedoch nicht. Es kann jedoch das Entwicklerkonto sein, das zum Testen einer Implementierung verwendet wird.

Wenn Sie mehrere Programme, Computer oder Ger�te autorisieren m�ssen, k�nnen Sie das Problem umgehen, indem Sie die Anzahl der Clients, die Sie pro Google-Konto autorisieren, auf 15 oder 20 beschr�nken. Wenn Sie Google Workspace-Administrator sind, k�nnen Sie zus�tzliche Nutzer mit Administratorberechtigungen erstellen und damit einige der Clients autorisieren.

Richtlinien zur Sitzungssteuerung f�r Organisationen der Google Cloud Platform (GCP)

Administratoren von GCP-Organisationen verlangen unter Umst�nden mithilfe der Google Cloud-Funktion zur Sitzungssteuerung, dass Nutzer w�hrend des Zugriffs auf GCP-Ressourcen h�ufig neu authentifizieren m�ssen. 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, f�r die der Cloud Platform-Bereich erforderlich ist. Wenn ein Nutzer eine Sitzungssteuerungsrichtlinie hat, schlagen Ihre API-Aufrufe nach Ablauf der Sitzungsdauer �hnlich wie bei einem Widerruf des Aktualisierungstokens fehl. Der Aufruf schl�gt mit dem Fehlertyp invalid_grant fehl. Anhand des Felds error_subtype kann zwischen einem widerrufenen Token und einem Fehler aufgrund einer Sitzungssteuerungsrichtlinie (z. B. "error_subtype": "invalid_rapt") unterschieden werden. Da die Sitzungsdauer in einem Kulanzzeitraum von 2 Stunden begrenzt sein kann, muss die Authentifizierung bis zu einer Stunde dauern.

Gleicherma�en d�rfen Sie f�r die Server-zu-Server-Bereitstellung keine Nutzeranmeldedaten verwenden oder deren Nutzung 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 der Nutzer nach Ablauf der Sitzungsdauer nicht noch einmal authentifiziert werden kann.

Weitere Informationen dazu, wie Sie Ihre Kunden bei der Bereitstellung dieses Features 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 werden den Bibliotheken weitere Funktionen hinzugefügt.