In diesem Dokument wird erläutert, wie Anwendungen auf Geräten wie Smartphones, Tablets und Computern die OAuth 2.0-Endpunkte von Google verwenden, um den Zugriff auf Google APIs zu autorisieren.
Mit OAuth 2.0 können Nutzer bestimmte Daten für eine Anwendung freigeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Beispielsweise kann eine Anwendung OAuth 2.0 verwenden, um die Berechtigung von Nutzern zum Speichern von Dateien in Google Drive zu erhalten.
Installierte Anwendungen werden auf einzelne Geräte verteilt und es wird davon ausgegangen, dass diese Anwendungen keine Secrets speichern können. Sie können auf Google APIs zugreifen, während der Nutzer in der App anwesend oder im Hintergrund ist.
Dieser Autorisierungsvorgang ähnelt dem für Webserveranwendungen. Der Hauptunterschied besteht darin, dass installierte Apps den Systembrowser öffnen und einen lokalen Weiterleitungs-URI angeben müssen, um Antworten des Google-Autorisierungsservers zu verarbeiten.
Alternativen
Für mobile Apps kannst du Google Log-in für Android oder iOS verwenden. Die Google Log-in-Clientbibliotheken verarbeiten die Authentifizierung und die Nutzerautorisierung und sind möglicherweise einfacher zu implementieren als das hier beschriebene untergeordnete Protokoll.
Informationen zu Apps auf Geräten, die keinen Systembrowser unterstützen oder die nur über eingeschränkte Eingabefunktionen verfügen, wie Fernseher, Spielekonsolen, Kameras oder Drucker, findest du unter OAuth 2.0 für Fernseher und Geräte oder Anmeldung auf Fernsehern und Geräten mit eingeschränkter Eingabe.
Bibliotheken und Beispiele
Wir empfehlen die folgenden Bibliotheken und Beispiele, um den in diesem Dokument beschriebenen OAuth 2.0-Vorgang zu implementieren:
Voraussetzungen
Die APIs für Ihr Projekt aktivieren
Jede Anwendung, die Google APIs aufruft, muss diese APIs in der API Consoleaktivieren.
So aktivieren Sie eine API für Ihr Projekt:
- Open the API Library im Google API Console.
- If prompted, select a project, or create a new one.
- In der API Library sind alle verfügbaren APIs nach Produktfamilie und Beliebtheit gruppiert. Wenn die API, die Sie aktivieren möchten, nicht in der Liste angezeigt wird, können Sie danach suchen oder sie in der entsprechenden Produktfamilie auf Alle ansehen klicken.
- Wählen Sie die API aus, die Sie aktivieren möchten, und klicken Sie dann auf die Schaltfläche Aktivieren.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
Anmeldedaten für die Autorisierung erstellen
Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, muss Anmeldedaten für die Autorisierung der Anwendung für den OAuth 2.0-Server von Google haben. In den folgenden Schritten wird erläutert, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann mit den Anmeldedaten auf APIs zugreifen, die Sie für dieses Projekt aktiviert haben.
- Go to the Credentials page.
- Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
- In den folgenden Abschnitten werden die Clienttypen und die Weiterleitungsmethoden beschrieben, die vom Google-Autorisierungsserver unterstützt werden. Wählen Sie den für Ihre Anwendung empfohlenen Clienttyp aus, benennen Sie den OAuth-Client und legen Sie die anderen Felder im Formular entsprechend fest.
Benutzerdefiniertes URI-Schema (Android, iOS, UWP)
Ein benutzerdefiniertes URI-Schema wird für Android-Apps, iOS-Apps und UWP-Apps (Universal Windows Platform) empfohlen.
Android
- Wählen Sie den Anwendungstyp Android aus.
- Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird im Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
- Geben Sie den Paketnamen Ihrer Android-App ein. Dieser Wert ist im Attribut
packagedes Elements<manifest>in der App-Manifestdatei definiert. - Geben Sie den SHA1-Signaturzertifikat-Fingerabdruck der App-Bereitstellung ein.
- Wenn deine App die App-Signatur von Google Play verwendet, kopiere den SHA-1-Fingerabdruck von der App-Signaturseite der Play Console.
- Wenn Sie Ihren eigenen Schlüsselspeicher und Signaturschlüssel verwalten, verwenden Sie das in Java enthaltene Dienstprogramm keytool, um Zertifikatsinformationen in einem für Menschen lesbaren Format zu drucken. Kopieren Sie den Wert
SHA1im AbschnittCertificate fingerprintsder keytool-Ausgabe. Weitere Informationen finden Sie unter Client authentifizieren in der Dokumentation zu Google APIs für Android.
- Klicken Sie auf Erstellen.
iOS
- Wählen Sie den Anwendungstyp iOS aus.
- Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird im Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
- Geben Sie die Bundle-ID für Ihre App ein. Die Bundle-ID ist der Wert des CFBundleIdentifier-Schlüssels in der Ressourcenliste für die Informationseigenschaft Ihrer App (info.plist). Der Wert wird am häufigsten im Bereich „Allgemein“ oder im Bereich „Signatur und Funktionen“ des Xcode-Projekteditors angezeigt. Die Bundle-ID wird auch auf der App Store-Website von Apple im Abschnitt „Allgemeine Informationen“ der Seite „App-Informationen“ für die App angezeigt.
- (Optional)
Geben Sie die App Store-ID Ihrer App ein, wenn die App im App Store von Apple veröffentlicht wurde. Die Store-ID ist ein numerischer String, der in jeder Apple App Store-URL enthalten ist.
- Öffne die Apple App Store App auf deinem iOS- oder iPadOS-Gerät.
- Suchen Sie nach Ihrer App.
- Klicken Sie auf die Schaltfläche „Teilen“ (quadratisch und Pfeil nach oben).
- Wählen Sie Link kopieren aus.
- Fügen Sie den Link in einen Texteditor ein. Die App Store-ID ist der letzte Teil der URL.
Beispiel:
https://apps.apple.com/app/google/id284815942
- (Optional)
Geben Sie Ihre Team-ID ein. Weitere Informationen findest du in der Dokumentation deines Apple-Entwicklerkontos unter Team-ID ermitteln.
- Klicken Sie auf Erstellen.
UWP
- Wählen Sie den Anwendungstyp Universelle Windows-Plattform aus.
- Geben Sie einen Namen für den OAuth-Client ein. Dieser Name wird im Credentials page Ihres Projekts angezeigt, um den Client zu identifizieren.
- Geben Sie die 12-stellige Microsoft Store-ID Ihrer App ein. Sie finden diesen Wert im Microsoft-Partnercenter auf der Seite App-Identität im Abschnitt „App-Verwaltung“.
- Klicken Sie auf Erstellen.
Bei UWP-Apps darf das benutzerdefinierte URI-Schema nicht länger als 39 Zeichen sein.
Loopback-IP-Adresse (macOS, Linux, Windows-Desktop)
Damit der Autorisierungscode mit dieser URL empfangen wird, muss Ihre Anwendung den lokalen Webserver beobachten. Das ist auf vielen, aber nicht auf allen Plattformen möglich. Wenn deine Plattform dies jedoch unterstützt, ist dies die empfohlene Methode zum Abrufen des Autorisierungscodes.
Wenn deine App die Autorisierungsantwort erhält, sollte sie für die Nutzerfreundlichkeit eine HTML-Seite anzeigen, die den Nutzer auffordert, den Browser zu schließen und zu deiner App zurückzukehren.
| Empfohlene Verwendung | macOS-, Linux- und Windows-Desktop-Apps (jedoch nicht die universelle Windows-Plattform) |
| Formularwerte | Wählen Sie als Anwendungstyp Desktop-App aus. |
Manuelles Kopieren/Einfügen
Zugriffsbereiche identifizieren
Bereiche ermöglichen es Ihrer Anwendung, nur den erforderlichen Zugriff auf die Ressourcen anzufordern, während Nutzer auch steuern können, wie viel Zugriff sie der Anwendung gewähren. Daher besteht möglicherweise eine inverse Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen.
Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche identifizieren, auf die Ihre App Zugriff benötigt.
Das Dokument OAuth 2.0 API-Bereiche enthält eine vollständige Liste der Bereiche, die Sie für den Zugriff auf Google APIs verwenden können.
OAuth 2.0-Zugriffstoken abrufen
Die folgenden Schritte zeigen, wie Ihre Anwendung mit dem OAuth 2.0-Server von Google interagiert, um die Einwilligung eines Nutzers einzuholen, eine API-Anfrage im Namen des Nutzers auszuführen. Ihre Anwendung muss diese Einwilligung haben, bevor sie eine Google API-Anfrage ausführen kann, die eine Nutzerautorisierung erfordert.
Schritt 1: Codeprüfung und Identitätsbestätigung generieren
Google unterstützt das Protokoll Proof Key for Code Exchange (Proof Key for Code Exchange), um die installierte Anwendung sicherer zu machen. Für jede Autorisierungsanfrage wird ein eindeutiger Codeprüfer erstellt. Der transformierte Wert „code_challenge“ wird an den Autorisierungsserver gesendet, um den Autorisierungscode abzurufen.
Codeprüfer erstellen
code_verifier ist ein kryptografischer zufälliger String mit hoher Entropie unter Verwendung der nicht reservierten Zeichen [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" mit einer Mindestlänge von 43 Zeichen und einer maximalen Länge von 128 Zeichen.
Die Code-Überprüfung sollte genügend Entropie haben, damit der Wert nicht erraten werden kann.
Code-Challenge erstellen
Es werden zwei Methoden zum Erstellen der Code-Herausforderung unterstützt.
| Methoden zum Generieren von Code-Herausforderungen | |
|---|---|
| S256 (empfohlen) | Die Code-Herausforderung ist der Base64-URL-Code (ohne Auffüllung) mit dem SHA256-Hash-Wert der Codeprüffunktion.
|
| einfach | Die Code-Herausforderung hat denselben Wert wie die oben erstellte Code-Prüfer.
|
Schritt 2: Anfrage an den OAuth 2.0-Server von Google senden
Senden Sie zum Abrufen der Nutzerautorisierung eine Anfrage an den Autorisierungsserver von Google unter https://accounts.google.com/o/oauth2/v2/auth. Dieser Endpunkt übernimmt die aktive Sitzungssuche, authentifiziert den Nutzer und erhält die Nutzereinwilligung. Der Endpunkt ist nur über SSL zugänglich und verweigert HTTP-Verbindungen (nicht SSL-Verbindungen).
Der Autorisierungsserver unterstützt die folgenden Abfragestringparameter für installierte Anwendungen:
| Parameter | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Erforderlich
Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in API Console Credentials page. |
||||||
redirect_uri |
Erforderlich
Legt fest, wie der Autorisierungsserver von Google eine Antwort an Ihre Anwendung sendet. Es gibt verschiedene Weiterleitungsoptionen für installierte Anwendungen und Sie haben Ihre Autorisierungsdaten im Hinblick auf eine bestimmte Weiterleitungsmethode eingerichtet. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in API Console
Credentials pageIhres Clients konfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, wird der Fehler In der folgenden Tabelle sehen Sie den entsprechenden
|
||||||
response_type |
Erforderlich
Legt fest, ob der Google OAuth 2.0-Endpunkt einen Autorisierungscode zurückgibt. Legen Sie den Parameterwert für installierte Anwendungen auf |
||||||
scope |
Erforderlich
Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte bilden die Grundlage für den Zustimmungsbildschirm, den Google dem Nutzer anzeigt. Mit Bereichen kann Ihre Anwendung nur den Zugriff auf die erforderlichen Ressourcen anfordern und Nutzer können auch steuern, welche Zugriffsrechte sie Ihrer Anwendung gewähren. Daher besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen. |
||||||
code_challenge |
Empfohlen
Gibt eine codierte |
||||||
code_challenge_method |
Empfohlen
Gibt an, welche Methode zum Codieren einer |
||||||
state |
Empfohlen
Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechtzuerhalten.
Der Server gibt den genauen Wert zurück, den Sie als Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung zu leiten, Nonces zu senden und eine websiteübergreifende Anfragefälschung zu verringern. Da Ihre |
||||||
login_hint |
Optional
Wenn die Anwendung weiß, welcher Nutzer sich authentifizieren möchte, kann sie mit diesem Parameter einen Hinweis für den Google-Authentifizierungsserver bereitstellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen. Dazu füllt er entweder das E-Mail-Feld im Anmeldeformular aus oder wählt die entsprechende Mehrfachanmeldung aus. Legen Sie den Parameterwert auf eine E-Mail-Adresse oder eine |
||||||
Beispiele für Autorisierungs-URLs
Auf den Tabs unten sehen Sie Beispiele für Autorisierungs-URLs der verschiedenen Weiterleitungs-URI-Optionen.
Die URLs sind bis auf den Wert des Parameters redirect_uri identisch. Die URLs enthalten außerdem die erforderlichen Parameter response_type und client_id sowie den optionalen Parameter state. Jede URL enthält Zeilenumbrüche und Leerzeichen zur besseren Lesbarkeit.
Benutzerdefiniertes URI-Schema
https://accounts.google.com/o/oauth2/v2/auth? scope=& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
Loopback-IP-Adresse
https://accounts.google.com/o/oauth2/v2/auth? scope=& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
Schritt 3: Google fordert den Nutzer zur Einwilligung auf
In diesem Schritt entscheidet der Nutzer, ob er Ihrer Anwendung den angeforderten Zugriff gewähren soll. In dieser Phase zeigt Google ein Einwilligungsfenster mit dem Namen Ihrer Anwendung und den Google API-Diensten an, auf die mit den Autorisierungsanmeldedaten des Nutzers eine Zugriffsberechtigung angefordert wird, sowie eine Zusammenfassung der zu gewährenden Zugriffsbereiche. Der Nutzer kann dann zustimmen, um Zugriff auf einen oder mehrere Bereiche zu gewähren, die von Ihrer Anwendung angefordert werden, oder die Anfrage abzulehnen.
Ihre Anwendung muss zu diesem Zeitpunkt nichts tun, da sie auf die Antwort des OAuth 2.0-Servers von Google wartet, der angibt, ob ein Zugriff gewährt wurde. Diese Antwort wird im folgenden Schritt erläutert.
Fehler
Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google können anstelle der erwarteten Authentifizierungs- und Autorisierungsabläufe Fehlermeldungen für Nutzer anzeigen. Die häufigsten Fehlercodes und Lösungsvorschläge sind unten aufgeführt.
admin_policy_enforced
Das Google-Konto kann einen oder mehrere Bereiche nicht autorisieren, die aufgrund der Richtlinien seines Google Workspace-Administrators angefordert wurden. Im Hilfeartikel Zugriff externer und interner Apps auf Google Workspace-Daten verwalten finden Sie weitere Informationen dazu, wie Administratoren den Zugriff auf alle oder sensible und eingeschränkte Bereiche einschränken können, bis der OAuth-Client-ID explizit Zugriff gewährt wird.
disallowed_useragent
Der Autorisierungsendpunkt wird in einem eingebetteten User-Agent angezeigt, der gemäß den OAuth 2.0-Richtlinien von Google unzulässig ist.
Android
Diese Fehlermeldung kann unter Android-Entwicklern angezeigt werden, wenn Autorisierungsanfragen in android.webkit.WebView geöffnet werden.
Entwickler sollten stattdessen Android-Bibliotheken wie Google Log-in für Android oder AppAuth für Android der OpenID Foundation verwenden.
Webentwickler können diesen Fehler erhalten, wenn eine Android-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von deiner Website zum OAuth 2.0-Autorisierungsendpunkt von Google wechselt. Entwickler sollten das Öffnen allgemeiner Links im Standard-Link-Handler des Betriebssystems zulassen, der sowohl Handler für Android-App-Links als auch die Standard-Browser-App enthält. Die Bibliothek Benutzerdefinierte Android-Tabs ist ebenfalls eine unterstützte Option.
iOS
iOS- und macOS-Entwickler erhalten möglicherweise diesen Fehler, wenn Autorisierungsanfragen in WKWebView geöffnet werden.
Entwickler sollten stattdessen iOS-Bibliotheken wie Google Log-in für iOS oder AppAuth für iOS der OpenID Foundation verwenden.
Dieser Fehler kann auftreten, wenn eine iOS- oder macOS-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von deiner Website zum OAuth 2.0-Autorisierungsendpunkt von Google wechselt. Entwickler sollten das Öffnen allgemeiner Links im Standard-Link-Handler des Betriebssystems zulassen, das sowohl Handler für universelle Links als auch die Standard-Browser-App umfasst. Die Bibliothek SFSafariViewController wird ebenfalls unterstützt.
org_internal
Die OAuth-Client-ID in der Anfrage ist Teil eines Projekts, das den Zugriff auf Google-Konten in einer bestimmten Google Cloud-Organisation beschränkt. Weitere Informationen zu dieser Konfigurationsoption finden Sie im Hilfeartikel OAuth-Zustimmungsbildschirm einrichten.
invalid_grant
Wenn du eine Codeprüfung und die Identitätsbestätigung verwendest, ist der Parameter code_callenge ungültig oder fehlt. Der Parameter code_challenge muss richtig festgelegt sein.
Beim Aktualisieren eines Zugriffstokens ist das Token möglicherweise abgelaufen oder ungültig. Authentifizieren Sie den Nutzer noch einmal und bitten Sie ihn um Zustimmung, um neue Tokens zu erhalten. Wenn dieser Fehler weiterhin auftritt, prüfen Sie, ob Ihre Anwendung korrekt konfiguriert wurde und ob Sie die richtigen Tokens und Parameter in Ihrer Anfrage verwenden. Andernfalls wurde das Nutzerkonto möglicherweise gelöscht oder deaktiviert.
redirect_uri_mismatch
Der in der Autorisierungsanfrage übergebene redirect_uri stimmt nicht mit einem autorisierten Weiterleitungs-URI für die OAuth-Client-ID überein. Prüfen Sie autorisierte Weiterleitungs-URIs in Google API Console Credentials page.
Die übergebene redirect_uri ist möglicherweise für den Clienttyp ungültig.
Der Parameter redirect_uri kann sich auf den OAuth-Out-of-Band-Vorgang (OOB) beziehen, der verworfen wurde und nicht mehr unterstützt wird. Informationen zum Einbinden der Integration finden Sie im Migrationsleitfaden.
Schritt 4: OAuth 2.0-Serverantwort verarbeiten
Die Art und Weise, wie Ihre Anwendung die Autorisierungsantwort empfängt, hängt vom verwendeten Weiterleitungs-URI-Schema ab. Unabhängig vom Schema enthält die Antwort entweder einen Autorisierungscode (code) oder einen Fehler (error). Zum Beispiel bedeutet error=access_denied, dass der Nutzer die Anfrage abgelehnt hat.
Wenn der Nutzer Zugriff auf Ihre Anwendung gewährt, können Sie den Autorisierungscode gegen ein Zugriffstoken und ein Aktualisierungstoken austauschen, wie im nächsten Schritt beschrieben.
Schritt 5: Autorisierungscode für Aktualisierungs- und Zugriffstokens austauschen
Um einen Autorisierungscode gegen ein Zugriffstoken auszutauschen, rufen Sie den Endpunkt https://oauth2.googleapis.com/token auf und legen die folgenden Parameter fest:
| Felder | |
|---|---|
client_id |
Die Client-ID, die von API Console Credentials pageerhalten wurde. |
client_secret |
Der Clientschlüssel, der von API Console Credentials pageerhalten wurde. |
code |
Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wurde. |
code_verifier |
Die Codeprüffunktion, die Sie in Schritt 1 erstellt haben. |
grant_type |
Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Feldes auf authorization_code festgelegt werden. |
redirect_uri |
Einer der Weiterleitungs-URIs, die für Ihr Projekt in der API Console
Credentials page für die angegebene client_id aufgeführt sind. |
Das folgende Snippet zeigt eine Beispielanfrage:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& client_secret=your_client_secret& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Google antwortet auf diese Anfrage, indem es ein JSON-Objekt mit einem kurzlebigen Zugriffstoken und einem Aktualisierungstoken zurückgibt.
Die Antwort umfasst die folgenden Felder:
| Felder | |
|---|---|
access_token |
Das Token, das Ihre Anwendung zum Autorisieren einer Google API-Anfrage sendet. |
expires_in |
Die verbleibende Lebensdauer des Zugriffstokens in Sekunden. |
id_token |
Hinweis:Dieses Attribut wird nur zurückgegeben, wenn Ihre Anfrage einen Identitätsbereich wie openid, profile oder email enthält. Der Wert ist ein JSON-Webtoken (JWT), das digital signierte Identitätsinformationen über den Nutzer enthält. |
refresh_token |
Ein Token, mit dem Sie ein neues Zugriffstoken abrufen können. Aktualisierungstokens sind gültig, bis der Nutzer den Zugriff widerruft. Für installierte Anwendungen werden immer Aktualisierungstokens zurückgegeben. |
scope |
Der von access_token gewährte Zugriffsbereich, ausgedrückt als Liste von Strings, bei denen die Leerzeichen durch Leerzeichen getrennt sind. |
token_type |
Der Typ des zurückgegebenen Tokens. Derzeit ist der Wert dieses Felds immer auf Bearer festgelegt. |
Das folgende Snippet zeigt eine Beispielantwort:
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"token_type": "Bearer",
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}
Google APIs aufrufen
Nachdem Ihre Anwendung ein Zugriffstoken erhalten hat, können Sie mit dem Token im Namen eines Nutzerkontos eine Google API aufrufen, wenn der Zugriffsbereich, der für die API erforderlich ist, gewährt wurde. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein, indem Sie entweder einen access_token-Abfrageparameter oder einen Authorization-HTTP-Header-Bearer-Wert einbinden. Wenn möglich, ist der HTTP-Header zu bevorzugen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen können Sie eine Clientbibliothek verwenden, um Aufrufe an Google APIs einzurichten (z. B. beim Aufruf der Drive Files API).
Sie können alle Google APIs ausprobieren und ihre Bereiche im OAuth 2.0 Playground ansehen.
Beispiele für HTTP GET
Ein Aufruf des Endpunkts
drive.files (Drive File API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen. Sie müssen ein eigenes Zugriffstoken angeben:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Hier ist ein Aufruf derselben API für den authentifizierten Nutzer mit dem Abfragestringparameter access_token:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
Beispiele für curl
Sie können diese Befehle mit der curl-Befehlszeile testen. Hier ein Beispiel, bei dem die HTTP-Header-Option (bevorzugt) verwendet wird:
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Oder die Option für den Abfragestringparameter:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Zugriffstokens aktualisieren
Zugriffstoken laufen in regelmäßigen Abständen ab und werden zu ungültigen Anmeldedaten für eine ähnliche API-Anfrage. Sie können ein Zugriffstoken aktualisieren, ohne den Nutzer um seine Berechtigung zu bitten (auch wenn er nicht anwesend ist), wenn Sie Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.
Zum Aktualisieren eines Zugriffstokens sendet die Anwendung eine HTTPS-POST-Anfrage an den Google-Autorisierungsserver (https://oauth2.googleapis.com/token), der die folgenden Parameter enthält:
| Felder | |
|---|---|
client_id |
Die von API Consoleabgerufene Client-ID. |
client_secret |
Der Clientschlüssel, der von API Consoleabgerufen wird.
(client_secret gilt nicht für Anfragen von Clients, die als Android-, iOS- oder Chrome-Anwendungen registriert sind.)
|
grant_type |
Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Feldes auf refresh_token festgelegt werden. |
refresh_token |
Das vom Autorisierungscode-Austausch zurückgegebene Aktualisierungstoken. |
Das folgende Snippet zeigt eine Beispielanfrage:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
Solange der Nutzer der Anwendung keinen Zugriff entzogen hat, gibt der Tokenserver ein JSON-Objekt zurück, das ein neues Zugriffstoken enthält. Das folgende Snippet zeigt eine Beispielantwort:
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
"token_type": "Bearer"
}
Beachten Sie, dass die Anzahl der ausgestellten Aktualisierungstokens begrenzt ist: ein Limit pro Client/Nutzer-Kombination und ein anderes pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens im Langzeitspeicher speichern und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.
Token widerrufen
In manchen Fällen möchte ein Nutzer den Zugriff auf eine Anwendung widerrufen. Ein Nutzer kann den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen findest du im Supportdokument unter Websites oder Apps mit Zugriff auf dein Konto entfernen.
Eine Anwendung kann auch den Zugriff, der ihr gewährt wurde, programmatisch widerrufen. Der programmatische Widerruf ist in Fällen wichtig, in denen ein Nutzer sich abmeldet, eine Anwendung entfernt oder die für eine Anwendung erforderlichen API-Ressourcen sich erheblich geändert haben. Mit anderen Worten: Ein Teil des Entfernungsprozesses kann eine API-Anfrage umfassen, mit der die zuvor für die Anwendung gewährten Berechtigungen entfernt werden.
Wenn Sie ein Token programmatisch widerrufen möchten, sendet Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke und fügt das Token als Parameter ein:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}
Das Token kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn das Token ein Zugriffstoken ist und ein entsprechendes Aktualisierungstoken hat, wird dieses ebenfalls widerrufen.
Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der HTTP-Statuscode der Antwort 200. Bei Fehlerbedingungen wird der HTTP-Statuscode 400 zusammen mit einem Fehlercode zurückgegeben.
Weiterführende Literatur
Viele der hier aufgeführten Best Practices werden im IETF Best Current Practice OAuth 2.0 for Native Apps beschrieben.