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.