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 aus dem 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 Gruppe von Werten variiert je nach Art der Anwendung, die Sie erstellen. Eine JavaScript-Anwendung benötigt beispielsweise kein Secret, eine Webserveranwendung jedoch schon.
Sie müssen einen OAuth-Client für die Plattform erstellen, auf der Ihre App ausgeführt wird, z. B.:
- Verwenden Sie für serverseitige oder JavaScript-Web-Apps den Clienttyp „Web“. Verwenden Sie diesen Clienttyp nicht für andere Anwendungen, z. B. native 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 universelle Windows-Plattform-Anwendungen den Clienttyp "Universelle Windows-Plattform".
- Verwende für Geräte mit begrenzter Eingabe wie Fernseher oder eingebettete Geräte den Clienttyp „Fernseher und Geräte mit begrenzter Eingabe“.
- Verwenden Sie Dienstkonten für Server-zu-Server-Interaktionen.
2. Fordern Sie ein Zugriffstoken vom Google-Autorisierungsserver an.
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. Bei der Anforderung eines Zugriffstokens 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 mithilfe einer 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 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 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.
Im Allgemeinen empfiehlt es sich, Bereiche nicht im Voraus, sondern inkrementell anzufordern, wenn der Zugriff erforderlich ist. 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 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 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 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 in der scope
der Tokenanfrage beschriebenen Vorgänge und Ressourcen gültig. 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 Zugriff auf eine Google API über die Lebensdauer eines Zugriffstokens hinaus 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 Suchparameter, die die Art 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 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.
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.
Weitere Informationen findest du 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.
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 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.
Weitere Informationen findest du 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. Ebenso kann Ihre Anwendung in Unternehmensszenarien 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 und eine Zugriffstokenanfrage im entsprechenden Format zu erstellen. Die 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.
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:
- Der Nutzer hat den Zugriff Ihrer App widerrufen.
- Das Aktualisierungstoken wurde seit sechs Monaten nicht verwendet.
- Der Nutzer hat das Passwort geändert und das Aktualisierungstoken enthält Gmail-Bereiche.
- Für das Nutzerkonto wurde die maximale Anzahl von (Live-)Aktualisierungstokens überschritten.
- Wenn ein Administrator
einen der in den Bereichen Ihrer App angeforderten Dienste auf „Eingeschränkt“ gesetzt hat (Fehler
admin_policy_enforced
). - Bei Google Cloud Platform APIs: Die vom Administrator festgelegte Sitzungsdauer wurde möglicherweise überschritten.
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 das Limit erreicht ist und ein neues Aktualisierungstoken erstellt wird, wird das älteste Aktualisierungstoken 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 müssen Nutzer möglicherweise regelmäßig neu authentifizieren, während sie auf GCP-Ressourcen zugreifen. Dazu verwenden sie die Sitzungssteuerungsfunktion von Google Cloud. 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 Platform-Bereich erforderlich ist. Wenn ein Nutzer eine Richtlinie für die Sitzungssteuerung eingerichtet hat, werden nach Ablauf der Sitzungsdauer Ihre API-Aufrufe ähnlich wie bei einem Widerruf des Aktualisierungstokens ausgelöst. Der Aufruf schlägt mit dem Fehlertyp invalid_grant
fehl. Über das Feld error_subtype
kann zwischen einem widerrufenen Token und einem Fehler aufgrund einer Richtlinie für die Sitzungssteuerung (z. B. "error_subtype": "invalid_rapt"
) unterschieden werden, da die Authentifizierungsdauer sehr begrenzt ist (2 Stunden zwischen 1 Stunde).
Ebenso dürfen Sie für die Server-zu-Server-Bereitstellung keine Nutzeranmeldedaten verwenden oder deren Verwendung 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.
- 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