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 aus der Google API Console ab. Ihre Clientanwendung fordert dann 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. 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. Auf übergeordneter Ebene sind fünf Schritte erforderlich:
1. Rufen Sie OAuth 2.0-Anmeldedaten von der Google API Consoleab.
Rufen Sie die 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 Gruppe der Werte variiert je nach Art der Anwendung, die Sie entwickeln. 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.:
- code Verwenden Sie für serverseitige oder JavaScript-Web-Apps den Clienttyp „web“. Verwenden Sie diesen Clienttyp nicht für andere Anwendungen wie native Apps oder mobile Apps.
- Verwenden Sie für Android-Apps den Clienttyp „Android“.
-
Verwenden Sie für iOS- und macOS-Apps den Clienttyp „iOS“.
- Verwenden Sie für Universal Windows Platform-Apps den Clienttyp „Universal Windows Platform“.
- tv Verwenden Sie für Geräte mit begrenzter Eingabe wie Fernseher oder eingebettete Geräte den Clienttyp „TVs and Limited Input devices“ (Fernseher und Geräte mit begrenzter Eingabe).
- host Verwenden Sie für Server-zu-Server-Interaktionen Dienstkonten.
2. Rufen Sie ein Zugriffstoken vom Google Authorization Server ab.
Bevor Ihre Anwendung mit einer 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 Menge der Ressourcen und Vorgänge, die mit einem Zugriffstoken zulässig sind. Bei der Anfrage für das Zugriffstoken sendet Ihre Anwendung einen oder mehrere Werte im Parameter scope.
Es gibt verschiedene Möglichkeiten, diese Anfrage zu stellen. Sie variieren je nach Art der Anwendung, die Sie entwickeln. Eine JavaScript-Anwendung kann beispielsweise ein Zugriffstoken über eine Browserweiterleitung zu Google anfordern, während eine auf einem Gerät ohne Browser installierte Anwendung 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 bereit ist, eine oder mehrere Berechtigungen zu erteilen, 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 mit diesem Token gewährten Zugriffsbereiche. Wenn der Nutzer die Berechtigung nicht erteilt, gibt der Server einen Fehler zurück.
Es empfiehlt sich, Bereiche inkrementell anzufordern, wenn der Zugriff erforderlich ist, anstatt im Voraus. Eine App, die das Speichern eines Termins in einem Kalender unterstützen möchte, sollte beispielsweise erst dann den 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 Zugriffstokenantwort enthaltenen Bereiche mit den Bereichen, die für den Zugriff auf Funktionen Ihrer Anwendung erforderlich sind, die von einem 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 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 Bereichs-Stringwerte einem einzelnen Zugriffsbereich zuordnen und für alle in der Anfrage zulässigen Werte denselben Bereichs-String 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 aufgefordert hat, den Bereich https://www.google.com/m8/feeds/ zu autorisieren. Für die Google People API-Methode people.updateContact ist der Bereich 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-Suchparameter zu senden. Wir empfehlen dies jedoch nicht, da URI-Parameter in Protokolldateien landen können, die nicht vollständig sicher sind. Außerdem sollten Sie unnötige URI-Parameternamen vermeiden, da dies eine gute REST-Praxis ist.
Zugriffstokens sind nur für die in der scope der Tokenanfrage beschriebenen Vorgänge und Ressourcen gültig. 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 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 den angeforderten Zugriffstyp angeben. Google übernimmt die Nutzerauthentifizierung, die Auswahl der Sitzung und die Einwilligung des Nutzers. Das Ergebnis ist ein Autorisierungscode, den die Anwendung gegen ein Zugriffs- und ein Aktualisierungstoken eintauschen kann.
Die Anwendung sollte das Aktualisierungstoken für die zukünftige Verwendung speichern und das Zugriffstoken verwenden, um auf eine Google API zuzugreifen. 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, Smartphones 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, und wählen Sie dann Android, Chrome-App, iOS, Universal Windows Platform (UWP) oder Desktop-App als Anwendungstyp aus.
Bei diesem Vorgang werden eine Client-ID und in einigen Fällen ein Clientschlüssel generiert, 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 zu einer Google-URL weiterleitet. Die URL enthält Abfrageparameter, die den angeforderten Zugriffstyp angeben. Google übernimmt die Nutzerauthentifizierung, die Auswahl der Sitzung und die Einwilligung des Nutzers. Das Ergebnis ist ein Autorisierungscode, den die Anwendung gegen ein Zugriffs- und ein Aktualisierungstoken eintauschen kann.
Die Anwendung sollte das Aktualisierungstoken für die zukünftige Verwendung speichern und das Zugriffstoken verwenden, um auf eine Google API zuzugreifen. 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 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 zu einer Google-URL weiterleitet. Die URL enthält Abfrageparameter, die den angeforderten Zugriffstyp angeben. Google übernimmt die Nutzerauthentifizierung, die Auswahl der Sitzung und die Einwilligung des Nutzers.
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änkter 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, die der Nutzer in der Anwendung sieht.
Der Nutzer ruft die URL und den Code auf dem Gerät ab und wechselt dann zu einem separaten Gerät oder Computer mit besseren Eingabefunktionen. 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 des Google-Servers ein Zugriffstoken und ein Aktualisierungstoken. Die Anwendung sollte das Aktualisierungstoken für die zukünftige Verwendung speichern und das Zugriffstoken verwenden, um auf eine Google-API zuzugreifen. 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 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 Einwilligung des Nutzers erforderlich. In Unternehmensszenarien kann Ihre Anwendung ebenfalls delegierten Zugriff auf einige Ressourcen anfordern.
Für diese Arten von Server-zu-Server-Interaktionen benötigen Sie ein Dienstkonto. Ein solches Konto ist einer Anwendung zugeordnet und nicht einem bestimmten Endnutzer. Ihre Anwendung ruft Google-APIs im Namen des Dienstkontos auf und es ist keine Einwilligung des Nutzers erforderlich. In Szenarien ohne Dienstkonto ruft Ihre Anwendung Google-APIs im Namen von Endnutzern auf. In diesem Fall ist manchmal eine Einwilligung des Nutzers erforderlich.
Die Anmeldedaten eines Dienstkontos, die Sie von Google API Consoleerhalten, enthalten eine generierte E-Mail-Adresse, die eindeutig ist, 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.
Token-Größe
Die Größe von Tokens kann variieren, bis zu den folgenden Grenzwerten:
Von der Security Token Service API von Google Cloud zurückgegebene Zugriffstokens sind ähnlich strukturiert wie OAuth 2.0-Zugriffstokens für Google APIs, haben aber andere Tokengrößenlimits. Weitere Informationen finden Sie in der API-Dokumentation.
Google behält sich das Recht vor, die Tokengröße innerhalb dieser Grenzen zu ändern. Ihre Anwendung muss daher variable Tokengrößen unterstützen.
Ablauf des Aktualisierungstokens
Sie müssen Ihren Code so schreiben, dass er auf die Möglichkeit vorbereitet ist, dass ein gewährtes Aktualisierungstoken nicht mehr funktioniert. Ein Aktualisierungstoken kann aus einem der folgenden Gründe nicht mehr funktionieren:
Für ein Google Cloud-Projekt mit einem OAuth-Zustimmungsbildschirm, der für einen externen Nutzertyp konfiguriert ist, und einem Veröffentlichungsstatus von „Testen“ wird ein Aktualisierungstoken ausgestellt, das nach 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 die 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 gilt 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. Das Konto eines Entwicklers, das zum Testen einer Implementierung verwendet wird, kann es jedoch überschreiten.
Wenn Sie mehrere Programme, Computer oder Geräte autorisieren müssen, können Sie die Anzahl der Clients, die Sie pro Google-Konto autorisieren, auf 15 oder 20 begrenzen. 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 festlegen, dass Nutzer sich häufig neu authentifizieren müssen, wenn sie auf GCP-Ressourcen zugreifen. Diese Richtlinie wirkt sich auf den Zugriff auf die Google Cloud Console, das Google Cloud SDK (auch bekannt als gcloud CLI) und alle OAuth-Drittanbieteranwendungen aus, für die der Cloud Platform-Bereich erforderlich ist. Wenn für einen Nutzer eine Richtlinie zur Sitzungssteuerung eingerichtet ist, schlagen Ihre API-Aufrufe nach Ablauf der Sitzungsdauer fehl, ä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 zu unterscheiden (z. B. "error_subtype": "invalid_rapt"). Da die Sitzungsdauern sehr kurz sein können (zwischen 1 und 24 Stunden), muss dieses Szenario ordnungsgemäß behandelt werden, indem eine Authentifizierungssitzung neu gestartet wird.
Ebenso dürfen Sie Nutzeranmeldedaten nicht für die Server-zu-Server-Bereitstellung verwenden oder die Verwendung von Nutzeranmeldedaten für die Server-zu-Server-Bereitstellung fördern. Wenn Nutzeranmeldedaten auf einem Server für lang andauernde 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 neu authentifiziert werden kann.
Weitere Informationen dazu, wie Sie Ihren Kunden bei der Bereitstellung 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.
- Google API-Clientbibliothek für Java
- Google API-Clientbibliothek für Python
- 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