Google APIs verwenden das OAuth 2.0-Protokoll für die Authentifizierung und Autorisierung. Google unterstützt gängige OAuth 2.0-Szenarien, z. B. für Webserver-, clientseitige, installierte und Anwendungen für Geräte mit begrenzter Eingabe.
Rufen Sie zuerst die OAuth 2.0-Clientanmeldedaten in der Google API Console ab. Anschließend fordert Ihre Clientanwendung ein Zugriffstoken vom Google-Autorisierungsserver an, extrahiert ein Token aus der Antwort und sendet das Token an die Google API, auf die Sie zugreifen möchten. Eine interaktive Demonstration der Verwendung von OAuth 2.0 mit Google (einschließlich der Option, eigene Clientanmeldedaten zu verwenden) finden Sie im OAuth 2.0 Playground.
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 über OAuth 2.0 auf eine Google API zugreifen. Auf übergeordneter Ebene führen Sie fünf Schritte aus:
1. Rufen Sie OAuth 2.0-Anmeldedaten aus der Google API Console ab.
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 Werte variieren je nach Art der Anwendung, die Sie erstellen. Für eine JavaScript-Anwendung ist beispielsweise 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 App ausgeführt wird, z. B.:
- Verwenden Sie für Android-Apps den Anwendungstyp Android.
-
Verwenden Sie für iOS-Apps den Anwendungstyp iOS.
- desktop_windows Verwenden Sie für Desktop-Apps (z. B. Windows-, macOS- oder Linux-Anwendungen oder CLI-Tools) den Anwendungstyp Desktop-App.
- code Verwenden Sie für serverseitige oder JavaScript-Webanwendungen den Anwendungstyp Webanwendung. Verwenden Sie diesen Anwendungstyp nicht für andere Anwendungen, z. B. native oder mobile Apps.
- chrome_extension Verwenden Sie für Chrome-Erweiterungen den Anwendungstyp Chrome-Erweiterung.
- tv Verwenden Sie für Geräte mit begrenzter Eingabe, z. B. Fernseher oder eingebettete Geräte, den Anwendungstyp Fernsehgeräte und Geräte mit begrenzter Eingabe.
- Host Verwenden Sie für Server-zu-Server-Interaktionen Dienstkonten. Es ist keine OAuth-Client-ID erforderlich.
2. Rufen Sie ein Zugriffstoken vom Google-Autorisierungsserver ab.
Bevor Ihre Anwendung über eine Google API auf private Daten zugreifen kann, muss sie ein Zugriffstoken erhalten, das den Zugriff auf diese API gewährt. Ein einzelnes Zugriffstoken kann unterschiedliche Zugriffsebenen für mehrere APIs gewähren. Ein variabler Parameter namens scope steuert die Gruppe von Ressourcen und Vorgängen, 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. Beispielsweise kann eine JavaScript-Anwendung ein Zugriffstoken über eine Browserweiterleitung zu Google anfordern, während eine Anwendung, die auf einem Gerät ohne Browser installiert ist, Webdienst-Anfragen verwendet. Weitere Informationen zum Senden der Anfrage finden Sie unter Scenarios und in den detaillierten Implementierungsleitfäden für die einzelnen App-Typen.
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 erteilen möchte, die von Ihrer Anwendung angefordert werden. Dieser Vorgang wird als Nutzereinwilligung bezeichnet.
Wenn der Nutzer mindestens eine Berechtigung gewährt, 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 durch dieses Token gewährt werden. Wenn der Nutzer die Berechtigung nicht erteilt, gibt der Server einen Fehler zurück.
Im Allgemeinen empfiehlt es sich, Bereiche schrittweise anzufordern, wenn der Zugriff erforderlich ist, und nicht im Voraus. Eine App, die das Speichern eines Termins in einem Kalender unterstützen möchte, sollte beispielsweise erst dann Zugriff auf Google Kalender anfordern, wenn der Nutzer auf die Schaltfläche „Zum 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 Zugriffstoken-Antwort enthaltenen Bereiche mit den Bereichen, die für den Zugriff auf Funktionen Ihrer Anwendung erforderlich sind, die vom Zugriff auf eine zugehörige Google API abhängen. Deaktiviere alle Funktionen deiner App, die ohne Zugriff auf die zugehörige API nicht funktionieren.
Der in Ihrer Anfrage enthaltene Bereich stimmt möglicherweise nicht mit dem in Ihrer Antwort enthaltenen Bereich ü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 mehrere Bereichsstringwerte einem einzelnen Zugriffsbereich zuordnen und denselben Bereichsstring für alle in der Anfrage zulässigen Werte 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 auffordert, den Bereich https://www.google.com/m8/feeds/ zu autorisieren. Die Google People API-Methode people.updateContact erfordert den gewährten Bereich https://www.googleapis.com/auth/contacts.
4. Zugriffstoken an eine API senden
Nachdem eine Anwendung ein Zugriffstoken erhalten hat, sendet sie das Token in einem HTTP-Anfrageheader an eine Google API. Es ist möglich, Tokens als URI-Abfragestring-Parameter zu senden. Wir empfehlen dies jedoch nicht, da URI-Parameter in Protokolldateien landen können, die nicht vollständig sicher sind. Außerdem ist es eine gute REST-Praxis, die Erstellung unnötiger URI-Parameternamen zu vermeiden.
Zugriffstokens sind nur für die Vorgänge und Ressourcen gültig, die im scope der Tokenanfrage beschrieben sind. 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 dieses Zugriffstoken jedoch mehrmals für ähnliche Vorgänge 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
In diesen Szenarien wird beschrieben, wie Sie mit OAuth 2.0 Autorisierungscodes anfordern und Zugriffs- und Aktualisierungstokens für verschiedene Arten von Anwendungen abrufen.
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 Suchparameter, die den Typ des angeforderten Zugriffs angeben. Google übernimmt die Nutzerauthentifizierung, die Sitzungsauswahl und die 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.
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-Erweiterung“, „iOS“ oder „Desktop-Anwendung“ aus.
Das Ergebnis ist eine Client-ID und in einigen Fällen ein Clientschlüssel, 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 Suchparameter, die den Typ des angeforderten Zugriffs angeben. Google übernimmt die Nutzerauthentifizierung, die Sitzungsauswahl und die Nutzereinwilligung. Das Ergebnis ist ein Autorisierungscode, den die Anwendung gegen ein Zugriffstoken eintauschen kann. Die Anwendung sollte das Zugriffstoken validieren, bevor es in eine Google API-Anfrage aufgenommen wird. Wenn das Token abläuft, wiederholt die Anwendung den Vorgang.
Optional kann ein Backend-Server den Autorisierungscode gegen ein Aktualisierungstoken eintauschen und dieses an einem sicheren Ort speichern. Sobald das Zugriffstoken abläuft, verwendet der Backend-Server das Aktualisierungstoken, um ein neues für die Anwendung abzurufen.
Weitere Informationen finden Sie unter Zugriff auf Google-Nutzerdaten autorisieren für Android, In einer iOS-App auf Google APIs zugreifen und OAuth 2.0 für Desktop-Apps.
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 zu einer Google-URL weiterleitet. Die URL enthält Suchparameter, die den Typ des angeforderten Zugriffs angeben. Google übernimmt die Nutzerauthentifizierung, die Sitzungsauswahl und die Nutzereinwilligung.
Das Ergebnis ist ein Zugriffstoken, das der Client validieren sollte, bevor er es in eine Google API-Anfrage einfügt. Wenn das Token abläuft, wiederholt die Anwendung den Vorgang.
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änkten Eingabemöglichkeiten 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, die die Anwendung dem Nutzer anzeigt.
Der Nutzer ruft die URL und den Code vom Gerät ab und wechselt dann zu einem separaten Gerät oder Computer mit besseren Eingabemöglichkeiten. Der Nutzer startet 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 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 abzurufen.
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 ihre eigene Identität gegenüber der API nachweisen, aber es ist 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. Dies ist ein Konto, das zu Ihrer Anwendung und nicht zu einem einzelnen Endnutzer gehört. Ihre Anwendung ruft Google APIs im Namen des Dienstkontos auf. Eine Nutzereinwilligung ist nicht erforderlich. In Szenarien ohne Dienstkonto ruft Ihre Anwendung Google APIs im Namen von Endnutzern auf. Manchmal ist die Nutzereinwilligung erforderlich.
Die Anmeldedaten eines Dienstkontos, die Sie über die Google API Console erhalten, umfassen eine generierte, eindeutige E-Mail-Adresse, eine Client-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 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.
Weitere Informationen finden Sie in der Dokumentation zu Dienstkonten.
Tokengröße
Tokens können unterschiedlich groß sein, bis zu den folgenden Limits:
Zugriffstokens, die von der Security Token Service API von Google Cloud zurückgegeben werden, sind ähnlich strukturiert wie OAuth 2.0-Zugriffstokens der Google API, haben aber andere Größenbeschränkungen. 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 daher variable Tokengrößen unterstützen.
Ablauf des Aktualisierungstokens
Sie müssen Ihren Code so schreiben, dass er die Möglichkeit berücksichtigt, dass ein gewährtes Aktualisierungstoken nicht mehr funktioniert. Ein Aktualisierungstoken funktioniert möglicherweise aus einem der folgenden Gründe nicht mehr:
Für ein Google Cloud Platform-Projekt mit einem OAuth-Zustimmungsbildschirm, der für einen externen Nutzertyp und den Veröffentlichungsstatus „Test“ konfiguriert ist, wird ein Aktualisierungstoken ausgestellt, das in 7 Tagen 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 ihre OpenID Connect-Entsprechungen).
Derzeit gilt ein Limit von 100 Aktualisierungstokens pro Google-Konto und OAuth 2.0-Client-ID. 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.
Es gibt auch ein höheres Limit für die Gesamtzahl der Aktualisierungstokens, die ein Nutzer- oder Dienstkonto für alle Clients haben kann. Die meisten normalen Nutzer werden dieses Limit nicht überschreiten, aber das Entwicklerkonto, das zum Testen einer Implementierung verwendet wird, möglicherweise schon.
Wenn Sie mehrere Programme, Maschinen 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. Wenn Sie Google Workspace-Administrator sind, können Sie zusätzliche Nutzer mit Administratorberechtigungen erstellen und diese verwenden, um einige der Clients zu autorisieren.
Umgang mit Richtlinien zur Sitzungssteuerung für Google Cloud Platform-Organisationen (GCP)
Administratoren von GCP-Organisationen können mit der Google Cloud-Sitzungssteuerung eine häufige erneute Authentifizierung von Nutzern erzwingen, die auf GCP-Ressourcen zugreifen. 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, die den Cloud Platform-Bereich erfordern. Wenn für einen Nutzer eine Richtlinie zur Sitzungssteuerung gilt, schlagen Ihre API-Aufrufe nach Ablauf der Sitzungsdauer fehl, ähnlich wie beim Widerruf des Aktualisierungstokens. 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 zu unterscheiden (z. B. "error_subtype": "invalid_rapt"). 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 Nutzeranmeldedaten nicht für die Server-zu-Server-Bereitstellung verwenden oder deren Verwendung fördern. Wenn Nutzeranmeldedaten auf einem Server für lang laufende Jobs oder Vorgänge 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 dieser Funktion unterstützen 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.
- Google Auth-Bibliothek für Java
- Google API-Clientbibliothek für Python
- Google API-Clientbibliothek für Dart
- Google API-Clientbibliothek für Go
- Google API-Clientbibliothek für .NET
- Google API-Clientbibliothek für Ruby
- Google API-Clientbibliothek für PHP
- Google API-Clientbibliothek für JavaScript
- GTMAppAuth – OAuth-Clientbibliothek für Mac und iOS