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

Rufen Sie zuerst OAuth 2.0-Clientanmeldedaten 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. Wie Sie OAuth 2.0 mit Google verwenden (einschließlich der Option zur Verwendung Ihrer eigenen Client-Anmeldedaten), wird im OAuth 2.0 Playground interaktiv demonstriert.

Auf dieser Seite finden Sie eine Übersicht über die von Google unterstützten OAuth 2.0-Autorisierungsszenarien sowie 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 folgen einem grundlegenden Muster, wenn sie mit OAuth 2.0 auf eine Google API zugreifen. Im Groben gehen Sie dabei so vor:

1. Rufen Sie OAuth 2.0-Anmeldedaten von der Google API Consoleab.

Rufen Sie Google API Console auf, um OAuth 2.0-Anmeldedaten wie eine Client-ID und einen Clientschlüssel abzurufen, die sowohl Google als auch 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 hingegen schon.

Sie müssen einen OAuth-Client für die Plattform erstellen, auf der Ihre App ausgeführt wird, z. B.:

2. Rufe ein Zugriffstoken vom Google Authorization Server ab.

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 unterschiedlichen Zugriff auf mehrere APIs gewähren. Ein variabler Parameter namens 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. So kann eine JavaScript-Anwendung beispielsweise ein Zugriffstoken mithilfe einer Browserweiterleitung an Google anfordern, während eine Anwendung, die auf einem Gerät ohne Browser installiert ist, Webdienstanfragen verwendet.

Für einige Anfragen ist ein Authentifizierungsschritt erforderlich, 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 von Ihrer 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) und eine Liste der Zugriffsbereiche, die mit diesem Token gewährt wurden. Wenn der Nutzer die Berechtigung nicht erteilt, gibt der Server einen Fehler zurück.

Es wird empfohlen, Zugriffsbereiche schrittweise anzufordern, wenn der Zugriff erforderlich ist, und nicht im Voraus. Eine App, die das Speichern eines Termins in einem Kalender unterstützen soll, sollte beispielsweise erst dann den Zugriff auf Google Kalender anfordern, wenn der Nutzer auf die Schaltfläche „Zu Google Kalender hinzufügen“ klickt. Weitere Informationen finden Sie unter Inkrementelle Autorisierung.

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

Vergleichen Sie die in der Antwort des Zugriffstokens enthaltenen Zugriffsbereiche mit den Zugriffsbereichen, die für den Zugriff auf Funktionen Ihrer Anwendung erforderlich sind, die vom Zugriff auf eine zugehörige Google API abhängen. Deaktivieren Sie alle Funktionen Ihrer App, die ohne Zugriff auf die zugehörige API nicht funktionieren.

Der in Ihrer Anfrage angegebene Umfang stimmt möglicherweise nicht mit dem in Ihrer Antwort angegebenen Umfang ü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 jeweiligen Google API. Eine API kann mehreren Stringwerten für den Geltungsbereich einen einzelnen Zugriffsbereich zuordnen und für alle in der Anfrage zulässigen Werte denselben String zurückgeben. Beispiel: Die Google People API kann einen Umfang von https://www.googleapis.com/auth/contacts zurückgeben, wenn eine App einen Nutzer aufgefordert hat, einen Umfang von https://www.google.com/m8/feeds/ zu autorisieren. Für die Google People API-Methode people.updateContact ist ein gewährter Umfang von https://www.googleapis.com/auth/contacts erforderlich.

4. Senden Sie das Zugriffstoken an eine API.

Nachdem eine Anwendung ein Zugriffstoken erhalten hat, sendet sie das Token in einem HTTP-Autorisierungsanfrageheader an eine Google API. Es ist möglich, Tokens als URI-Suchstringparameter zu senden, wir empfehlen es jedoch nicht, da URI-Parameter in Protokolldateien landen können, die nicht vollständig sicher sind. Außerdem ist es eine gute REST-Praxis, unnötige URI-Parameternamen zu vermeiden.

Zugriffstokens sind nur für die Vorgänge und Ressourcen gültig, die in der scope der Tokenanfrage beschrieben sind. Wenn beispielsweise ein Zugriffstoken für die Google Kalender API ausgestellt wird, gewährt es keinen Zugriff auf die Google Kontakte API. Sie können dieses Zugriffstoken jedoch für ähnliche Vorgänge mehrmals an die Google Kalender API senden.

5. Aktualisieren Sie gegebenenfalls das Zugriffstoken.

Zugriffstokens haben eine begrenzte Lebensdauer. Wenn Ihre Anwendung über die Lebensdauer eines einzelnen Zugriffstokens hinaus auf eine Google API zugreifen muss, 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 auf eine Google-URL umleitet. Die URL enthält Abfrageparameter, die den angeforderten Zugriffstyp angeben. Google übernimmt die Nutzerauthentifizierung, die Sitzungsauswahl und die Nutzereinwilligung. Das Ergebnis ist ein Autorisierungscode, den die Anwendung gegen ein Zugriffstoken und ein Aktualisierungstoken eintauschen kann.

Die Anwendung sollte das Aktualisierungstoken für die spätere 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 abzurufen.

Ihre Anwendung sendet eine Tokenanfrage an den Google-Autorisierungsserver, erhält einen Autorisierungscode, tauscht den Code gegen ein Token aus und ruft mit dem Token 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 Google API Console erstellen, geben Sie an, dass es sich um eine installierte Anwendung handelt, und wählen Sie dann „Android“, „Chrome App“, „iOS“, „Universal Windows Platform (UWP)“ oder „Desktop-Anwendung“ als Anwendungstyp aus.

Das Verfahren führt zu einer Client-ID und in einigen Fällen zu einem Clientschlüssel, die 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 auf eine Google-URL umleitet. Die URL enthält Abfrageparameter, die den angeforderten Zugriffstyp angeben. Google übernimmt die Nutzerauthentifizierung, die Sitzungsauswahl und die Nutzereinwilligung. Das Ergebnis ist ein Autorisierungscode, den die Anwendung gegen ein Zugriffstoken und ein Aktualisierungstoken eintauschen kann.

Die Anwendung sollte das Aktualisierungstoken für die spätere 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 abzurufen.

Ihre Anwendung sendet eine Tokenanfrage an den Google-Autorisierungsserver, erhält einen Autorisierungscode, tauscht den Code gegen ein Token aus und ruft mit dem Token einen Google API-Endpunkt auf.

Weitere Informationen finden Sie unter OAuth 2.0 für installierte Anwendungen verwenden.

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 auf eine Google-URL umleitet. Die URL enthält Abfrageparameter, die den angeforderten Zugriffstyp 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 einfügt. Wenn das Token abläuft, wiederholt die Anwendung den Vorgang.

Ihre JS-Anwendung sendet eine Tokenanfrage an den Google-Autorisierungsserver, erhält ein Token, validiert es und ruft damit einen Google API-Endpunkt auf.

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 eingeschränkter Eingabe laufen, z. B. Spielekonsolen, Videokameras und Drucker.

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 ruft die URL und den Code auf dem Gerät ab und wechselt dann zu einem anderen Gerät oder Computer mit umfangreicheren Eingabemöglichkeiten. Der Nutzer öffnet einen Browser, ruft die angegebene URL auf, meldet sich an und gibt den Code ein.

In der Zwischenzeit fragt die Anwendung in einem bestimmten Intervall eine Google-URL 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 spätere 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 abzurufen.

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 in Ihrem Namen handeln, ohne auf Nutzerdaten zuzugreifen. In diesen Fällen muss Ihre Anwendung ihre Identität gegenüber der API nachweisen, aber es ist keine Nutzereinwilligung erforderlich. In Unternehmensszenarien kann Ihre Anwendung ebenfalls delegierten Zugriff auf einige Ressourcen anfordern.

Für diese Art von Server-zu-Server-Interaktionen benötigen Sie ein Dienstkonto. Ein solches Konto gehört zu Ihrer Anwendung und nicht zu einem einzelnen 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 von der Google API Consoleerhalten, umfassen eine eindeutige generierte E-Mail-Adresse, eine Kunden-ID und mindestens ein öffentliches/privates Schlüsselpaar. 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, 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 Autorisierungsserver von Google anzufordern, und ruft dann mit dem Token einen Google API-Endpunkt auf. Es ist kein Endnutzer beteiligt.

Weitere Informationen finden Sie in der Dokumentation zu Dienstkonten.

Tokengröße

Tokens können eine Größe von bis zu 256 Byte haben.

  • 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 wie OAuth 2.0-Zugriffstokens der Google API, haben aber andere Einschränkungen bei der 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. Ihre Anwendung muss variable Tokengrößen entsprechend unterstützen.

Ablauf des Aktualisierungstokens

Sie müssen Ihren Code so schreiben, dass die Möglichkeit berücksichtigt wird, dass ein gewährtes Aktualisierungstoken möglicherweise nicht mehr funktioniert. Ein Aktualisierungstoken funktioniert möglicherweise aus einem der folgenden Gründe nicht mehr:

Für ein Google Cloud-Plattformprojekt mit einem OAuth-Zustimmungsbildschirm, der für einen externen Nutzertyp konfiguriert ist und den Veröffentlichungsstatus „Testen“ hat, wird ein Aktualisierungstoken mit einer Gültigkeitsdauer von 7 Tagen ausgegeben, 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 ihre OpenID Connect-Entsprechungen).

Derzeit ist die Anzahl der Aktualisierungstokens pro Google-Konto und OAuth 2.0-Client-ID auf 100 angesetzt. Wenn diese Beschränkung erreicht wurde, wird das älteste Aktualisierungstoken beim Erstellen eines neuen automatisch und 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 Nutzerkonto oder Dienstkonto für alle Clients haben kann. Die meisten normalen Nutzer werden dieses Limit nicht überschreiten, aber das Konto eines Entwicklers, das zum Testen einer Implementierung verwendet wird, könnte es erreichen.

Wenn Sie mehrere Programme, Computer oder Geräte autorisieren möchten, können 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 diese verwenden, um einige der Kunden zu autorisieren.

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

Administratoren von GCP-Organisationen können mithilfe der Google Cloud-Sitzungssteuerung festlegen, dass sich Nutzer bei jedem Zugriff auf GCP-Ressourcen noch einmal authentifizieren müssen. 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-Plattformbereich erforderlich ist. Wenn für einen Nutzer eine Richtlinie zur Sitzungssteuerung gilt, werden Ihre API-Aufrufe nach Ablauf der Sitzungsdauer mit einem Fehler beendet, ähnlich wie bei einem widerrufenen Aktualisierungstoken. 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 Richtlinie zur Sitzungssteuerung (z. B. "error_subtype": "invalid_rapt") zu unterscheiden. Da die Sitzungsdauer sehr begrenzt sein kann (zwischen 1 Stunde und 24 Stunden), muss dieses Szenario durch einen Neustart einer Authentifizierungssitzung ordnungsgemäß behandelt werden.

Ebenso dürfen Sie keine Nutzeranmeldedaten für die Server-zu-Server-Bereitstellung verwenden oder die Verwendung solcher Daten fördern. Wenn Nutzeranmeldedaten für lang laufende Jobs oder Vorgänge auf einem Server bereitgestellt werden und ein Kunde Richtlinien zur Sitzungssteuerung auf diese Nutzer anwendet, schlägt die Serveranwendung fehl, da der Nutzer nicht noch einmal authentifiziert werden kann, wenn die Sitzungsdauer abgelaufen ist.

Weitere Informationen dazu, wie Sie Ihren Kunden bei der Implementierung dieser Funktion helfen können, finden Sie in diesem Hilfeartikel für Administratoren.

Clientbibliotheken

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