In diesem Dokument wird erläutert, wie Sie die OAuth 2.0-Autorisierung implementieren, um von einer JavaScript-Webanwendung aus auf Google APIs zuzugreifen. 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. Eine Anwendung kann beispielsweise OAuth 2.0 verwenden, um von Nutzern die Berechtigung zum Speichern von Dateien in ihrem Google Drive zu erhalten.
Dieser OAuth 2.0-Vorgang wird als impliziter Ablauf für die Berechtigungserteilung bezeichnet. Sie ist für Anwendungen konzipiert, die nur dann auf APIs zugreifen, wenn der Nutzer in der Anwendung aktiv ist. In diesen Anwendungen können keine vertraulichen Informationen gespeichert werden.
Bei diesem Ablauf öffnet Ihre App eine Google-URL, in der Ihre App und die Art des erforderlichen API-Zugriffs anhand von Abfrageparametern identifiziert werden. Sie können die URL im aktuellen Browserfenster oder in einem Pop-up öffnen. Der Nutzer kann sich bei Google authentifizieren und die angeforderten Berechtigungen gewähren. Google leitet den Nutzer dann zurück zu Ihrer App. Die Weiterleitung enthält ein Zugriffstoken, das Ihre App überprüft und dann zum Senden von API-Anfragen verwendet.
Google APIs Client Library und Google Identity Services
Wenn Sie die Google APIs-Clientbibliothek für JavaScript verwenden, um autorisierte Aufrufe an Google zu senden, sollten Sie die JavaScript-Bibliothek Google Identity Services verwenden, um den OAuth 2.0-Vorgang zu verarbeiten. Weitere Informationen finden Sie im Tokenmodell von Google Identity Services, das auf dem OAuth 2.0-Vorgang implicit grant basiert.
Vorbereitung
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 in der Google API Console.
- If prompted, select a project, or create a new one.
- In der API Library finden Sie 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 die Suchfunktion verwenden oder in der zugehörigen Produktfamilie auf Alle ansehen klicken.
- Wählen Sie die gewünschte API aus 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
Alle Anwendungen, die OAuth 2.0 für den Zugriff auf Google APIs verwenden, müssen Autorisierungsdaten haben, die die Anwendung beim OAuth 2.0-Server von Google identifizieren. 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.
- Wählen Sie den Anwendungstyp Webanwendung aus.
- Füllen Sie es aus. Anwendungen, die mit JavaScript autorisierte Google API-Anfragen stellen, müssen autorisierte JavaScript-Quellen angeben. Die Ursprünge identifizieren die Domains, von denen aus Ihre Anwendung Anfragen an den OAuth 2.0-Server senden kann. Diese Ursprünge müssen den Validierungsregeln von Google entsprechen.
Zugriffsbereiche identifizieren
Mithilfe von Bereichen wird ermöglicht, dass eine Anwendung nur für benötigte Ressourcen den Zugriff anfordern kann, während Nutzer wiederum steuern können, wie viel Zugriff sie der Anwendung gewähren. Daher besteht möglicherweise ein umgekehrter Zusammenhang 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 also die Bereiche ermitteln, für die Ihre Anwendung eine Zugriffsberechtigung benötigt.
Das Dokument OAuth 2.0 API Scopes enthält eine vollständige Liste der Bereiche, die Sie für den Zugriff auf Google APIs verwenden können.
OAuth 2.0-Zugriffstokens abrufen
In den folgenden Schritten wird gezeigt, 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 benötigt diese Einwilligung, bevor sie eine Google API-Anfrage ausführen kann, für die eine Nutzerautorisierung erforderlich ist.
Schritt 1: Weiterleitung zum OAuth 2.0-Server von Google
Wenn Sie die Berechtigung zum Zugriff auf die Daten eines Nutzers anfordern möchten, leiten Sie den Nutzer zum OAuth 2.0-Server von Google weiter.
OAuth 2.0-Endpunkte
Generieren Sie eine URL, um Zugriff über den OAuth 2.0-Endpunkt von Google unter https://accounts.google.com/o/oauth2/v2/auth anzufordern. Auf diesen Endpunkt kann über HTTPS zugegriffen werden. Normale HTTP-Verbindungen werden abgelehnt.
Der Google-Autorisierungsserver unterstützt die folgenden Suchstringparameter für Webanwendungsserver:
| Parameter | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Erforderlich
Die Client-ID für Ihre Anwendung. Sie finden diesen Wert unter API Console Credentials page. |
||||||
redirect_uri |
Erforderlich
Bestimmt, wohin der API-Server den Nutzer weiterleitet, nachdem er den Autorisierungsvorgang abgeschlossen hat. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in der API Console
Credentials pageIhres Clients konfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten Weiterleitungs-URI für die angegebene Das Schema ( |
||||||
response_type |
Erforderlich
Bei JavaScript-Anwendungen muss der Wert des Parameters auf |
||||||
scope |
Erforderlich
Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen angeben, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte werden auf dem Zustimmungsbildschirm angezeigt, den Google dem Nutzer präsentiert. Mithilfe von Bereichen wird ermöglicht, dass eine Anwendung nur für benötigte Ressourcen den Zugriff anfordern kann, während Nutzer wiederum steuern können, wie viel Zugriff sie der Anwendung gewähren. Daher besteht ein umgekehrter Zusammenhang zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen. Wir empfehlen, dass Ihre Anwendung nach Möglichkeit den Zugriff auf Autorisierungsbereiche im Kontext anfordert. Wenn Sie den Zugriff auf Nutzerdaten im Kontext über eine schrittweise Autorisierung anfordern, können Nutzer leichter nachvollziehen, warum Ihre Anwendung den angeforderten Zugriff benötigt. |
||||||
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 weiterzuleiten, Nonces zu senden und websiteübergreifende Anfragefälschungen zu verhindern. Da Ihre |
||||||
include_granted_scopes |
Optional
Ermöglicht es Anwendungen, mithilfe der schrittweisen Autorisierung den Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf |
||||||
enable_granular_consent |
Optional
Die Standardeinstellung ist Wenn Google detaillierte Berechtigungen für eine Anwendung aktiviert, hat dieser Parameter keine Auswirkungen mehr. |
||||||
login_hint |
Optional
Wenn Ihre Anwendung weiß, welcher Nutzer sich authentifizieren möchte, kann sie mit diesem Parameter einen Hinweis an den Google-Authentifizierungsserver senden. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen, indem er entweder das E-Mail-Feld im Anmeldeformular ausfüllt oder die entsprechende Sitzung mit mehreren Anmeldungen auswählt. Legen Sie den Parameterwert auf eine E-Mail-Adresse oder |
||||||
prompt |
Optional
Eine durch Leerzeichen getrennte Liste von Prompts, die dem Nutzer präsentiert werden sollen. Dabei wird zwischen Groß- und Kleinschreibung unterschieden. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur beim ersten Mal aufgefordert, wenn Ihr Projekt Zugriff anfordert. Weitere Informationen finden Sie unter Nutzer zur erneuten Einwilligung auffordern. Folgende Werte sind möglich:
|
||||||
Beispiel für eine Weiterleitung zum Autorisierungsserver von Google
Unten sehen Sie eine Beispiel-URL mit Zeilenumbrüchen und Leerzeichen für eine bessere Lesbarkeit.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
Nachdem du die Anfrage-URL erstellt hast, leite den Nutzer dorthin weiter.
JavaScript-Beispielcode
Im folgenden JavaScript-Snippet wird gezeigt, wie der Autorisierungsablauf in JavaScript ohne Verwendung der Clientbibliothek für JavaScript von Google APIs gestartet wird. Da dieser OAuth 2.0-Endpunkt keine CORS-Unterstützung (Cross-Origin Resource Sharing) bietet, wird mit dem Snippet ein Formular erstellt, über das die Anfrage an diesen Endpunkt geöffnet wird.
/* * Create form to request access token from Google's OAuth 2.0 server. */ function oauthSignIn() { // Google's OAuth 2.0 endpoint for requesting an access token var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth'; // Create <form> element to submit parameters to OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'GET'); // Send as a GET request. form.setAttribute('action', oauth2Endpoint); // Parameters to pass to OAuth 2.0 endpoint. var params = {'client_id': 'YOUR_CLIENT_ID', 'redirect_uri': 'YOUR_REDIRECT_URI', 'response_type': 'token', 'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly', 'include_granted_scopes': 'true', 'state': 'pass-through value'}; // Add form parameters as hidden input values. for (var p in params) { var input = document.createElement('input'); input.setAttribute('type', 'hidden'); input.setAttribute('name', p); input.setAttribute('value', params[p]); form.appendChild(input); } // Add form to page and submit it to open the OAuth 2.0 endpoint. document.body.appendChild(form); form.submit(); }
Schritt 2: Google fordert den Nutzer zur Einwilligung auf
In diesem Schritt entscheidet der Nutzer, ob er Ihrer Anwendung den angeforderten Zugriff gewährt. In dieser Phase zeigt Google ein Zustimmungsfenster an, in dem der Name Ihrer Anwendung und die Google API-Dienste angezeigt werden, für die mit den Autorisierungsanmeldedaten des Nutzers eine Berechtigung angefordert wird. Außerdem wird eine Zusammenfassung der zu gewährenden Zugriffsbereiche angezeigt. Der Nutzer kann dann zustimmen, Zugriff auf einen oder mehrere von Ihrer Anwendung angeforderte Bereiche zu gewähren, oder die Anfrage ablehnen.
Ihre Anwendung muss in dieser Phase nichts tun, da sie auf die Antwort vom OAuth 2.0-Server von Google wartet, die angibt, ob Zugriff gewährt wurde. Diese Antwort wird im nächsten Schritt erläutert.
Fehler
Bei Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google werden möglicherweise nutzerorientierte Fehlermeldungen anstelle der erwarteten Authentifizierungs- und Autorisierungsabläufe angezeigt. Im Folgenden finden Sie häufige Fehlercodes und empfohlene Lösungen.
admin_policy_enforced
Das Google-Konto kann aufgrund der Richtlinien des Google Workspace-Administrators einen oder mehrere der angeforderten Bereiche nicht autorisieren. Im Hilfeartikel für Google Workspace-Administratoren Zugriff externer und interner Apps auf Google Workspace-Daten verwalten finden Sie weitere Informationen dazu, wie ein Administrator den Zugriff auf alle oder vertrauliche und eingeschränkte Bereiche einschränken kann, bis der Zugriff Ihrer OAuth-Client-ID ausdrücklich gewährt wird.
disallowed_useragent
Der Autorisierungsendpunkt wird in einem eingebetteten User-Agent angezeigt, der gemäß den OAuth 2.0-Richtlinien von Google nicht zulässig ist.
Android
Android-Entwickler sehen diese Fehlermeldung möglicherweise, wenn sie Autorisierungsanfragen in android.webkit.WebView öffnen.
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 Ihrer Website zum OAuth 2.0-Autorisierungsendpunkt von Google gelangt. Entwickler sollten zulassen, dass allgemeine Links im Standard-Link-Handler des Betriebssystems geöffnet werden. Dazu gehören sowohl Android App Link-Handler als auch die Standard-Browser-App. Die Android Custom Tabs-Bibliothek ist ebenfalls eine unterstützte Option.
iOS
iOS- und macOS-Entwickler können diesen Fehler erhalten, wenn sie Autorisierungsanfragen in WKWebView öffnen.
Entwickler sollten stattdessen iOS-Bibliotheken wie Google Log-in für iOS oder AppAuth für iOS der OpenID Foundation verwenden.
Webentwickler können diesen Fehler erhalten, wenn eine iOS- oder macOS-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von Ihrer Website zum OAuth 2.0-Autorisierungsendpunkt von Google gelangt. Entwickler sollten zulassen, dass allgemeine Links im Standard-Link-Handler des Betriebssystems geöffnet werden. Dazu gehören sowohl Universal Links-Handler als auch die Standardbrowser-App. Die SFSafariViewController-Bibliothek ist ebenfalls eine unterstützte Option.
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 einschränkt. Weitere Informationen zu dieser Konfigurationsoption finden Sie im Hilfeartikel „OAuth-Zustimmungsbildschirm einrichten“ im Abschnitt Nutzertyp.
invalid_client
Der Ursprung, von dem aus die Anfrage gesendet wurde, ist für diesen Client nicht autorisiert. Weitere Informationen finden Sie unter origin_mismatch.
invalid_grant
Bei der Verwendung der inkrementellen Autorisierung ist das Token möglicherweise abgelaufen oder ungültig. Authentifizieren Sie den Nutzer noch einmal und bitten Sie um seine Einwilligung, um neue Tokens zu erhalten. Wenn dieser Fehler weiterhin auftritt, prüfen Sie, ob Ihre Anwendung richtig konfiguriert ist und Sie die richtigen Tokens und Parameter in Ihrer Anfrage verwenden. Andernfalls wurde das Nutzerkonto möglicherweise gelöscht oder deaktiviert.
origin_mismatch
Das Schema, die Domain und/oder der Port des JavaScript-Codes, von dem die Autorisierungsanfrage stammt, stimmen möglicherweise nicht mit einem autorisierten JavaScript-Ursprungs-URI überein, der für die OAuth-Client-ID registriert ist. Sehen Sie sich die autorisierten JavaScript-Quellen in der Google API Console Credentials pagean.
redirect_uri_mismatch
Die in der Autorisierungsanfrage übergebene redirect_uri stimmt nicht mit einem autorisierten Weiterleitungs-URI für die OAuth-Client-ID überein. Überprüfen Sie die autorisierten Weiterleitungs-URIs in Google API Console Credentials page.
Das Schema, die Domain und/oder der Port des JavaScript-Codes, von dem die Autorisierungsanfrage stammt, stimmen möglicherweise nicht mit einem autorisierten JavaScript-Ursprungs-URI überein, der für die OAuth-Client-ID registriert ist. Prüfen Sie die autorisierten JavaScript-Quellen in der Google API Console Credentials page.
Der Parameter redirect_uri bezieht sich möglicherweise auf den OAuth-Out-of-Band-Ablauf (OOB), der eingestellt wurde und nicht mehr unterstützt wird. Weitere Informationen zur Aktualisierung Ihrer Integration finden Sie im Migrationsleitfaden.
invalid_request
Bei Ihrer Anfrage ist ein Fehler aufgetreten. Das kann verschiedene Gründe haben:
- Die Anfrage war nicht richtig formatiert.
- In der Anfrage fehlen erforderliche Parameter.
- Die Anfrage verwendet eine Autorisierungsmethode, die von Google nicht unterstützt wird. Prüfen, ob für die OAuth-Integration eine empfohlene Integrationsmethode verwendet wird
Schritt 3: OAuth 2.0-Serverantwort verarbeiten
OAuth 2.0-Endpunkte
Der OAuth 2.0-Server sendet eine Antwort an die in Ihrer Zugriffstokenanfrage angegebene redirect_uri.
Wenn der Nutzer die Anfrage genehmigt, enthält die Antwort ein Zugriffstoken. Wenn der Nutzer die Anfrage nicht genehmigt, enthält die Antwort eine Fehlermeldung. Das Zugriffstoken oder die Fehlermeldung wird im Hash-Fragment des Weiterleitungs-URIs zurückgegeben, wie unten dargestellt:
Eine Antwort mit einem Zugriffstoken:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
Neben dem Parameter
access_tokenenthält der Fragment-String auch den Parametertoken_type, der immer aufBearerfestgelegt ist, und den Parameterexpires_in, der die Gültigkeitsdauer des Tokens in Sekunden angibt. Wenn der Parameterstatein der Zugriffstokenanfrage angegeben wurde, ist sein Wert auch in der Antwort enthalten.- Eine Fehlerantwort:
https://oauth2.example.com/callback#error=access_denied
Beispiel für eine OAuth 2.0-Serverantwort
Sie können diesen Ablauf testen, indem Sie auf die folgende Beispiel-URL klicken. Dabei wird schreibgeschützter Zugriff angefordert, um Metadaten für Dateien in Google Drive aufzurufen, und schreibgeschützter Zugriff, um Ihre Google Kalender-Termine aufzurufen:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
Nach Abschluss des OAuth 2.0-Vorgangs wirst du zu http://localhost/oauth2callback weitergeleitet. Diese URL führt zu einem 404 NOT FOUND-Fehler, es sei denn, auf Ihrem lokalen Computer wird zufällig eine Datei an dieser Adresse bereitgestellt. Im nächsten Schritt erfahren Sie mehr über die Informationen, die im URI zurückgegeben werden, wenn der Nutzer zu Ihrer Anwendung zurückgeleitet wird.
Schritt 4: Prüfen, welche Berechtigungen Nutzer gewährt haben
Wenn Sie mehrere Bereiche gleichzeitig anfordern, gewähren Nutzer möglicherweise nicht alle Bereiche, die Ihre App anfordert. Ihre App sollte immer prüfen, welche Bereiche vom Nutzer gewährt wurden, und bei einer Ablehnung von Bereichen die entsprechenden Funktionen deaktivieren. Weitere Informationen finden Sie unter Detaillierte Berechtigungen verwalten.
OAuth 2.0-Endpunkte
Ob der Nutzer Ihrer Anwendung Zugriff auf einen bestimmten Bereich gewährt hat, sehen Sie im Feld scope in der Antwort des Zugriffstokens. Die Zugriffsbereiche, die durch das access_token gewährt werden, als Liste von durch Leerzeichen getrennten Strings, die zwischen Groß- und Kleinschreibung unterscheiden.
In der folgenden Beispielantwort für ein Zugriffstoken ist beispielsweise zu sehen, dass der Nutzer Ihrer Anwendung Lesezugriff auf Drive-Aktivitäten und Kalendertermine gewährt hat:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Google APIs aufrufen
OAuth 2.0-Endpunkte
Nachdem Ihre Anwendung ein Zugriffstoken erhalten hat, können Sie damit im Namen eines bestimmten Nutzerkontos eine Google API aufrufen, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Dazu fügen Sie das Zugriffstoken in eine Anfrage an die API ein, indem Sie entweder einen access_token-Abfrageparameter oder einen Authorization-HTTP-Header-Bearer-Wert angeben. Wenn möglich, ist der HTTP-Header vorzuziehen, da Suchstrings in Serverprotokollen in der Regel sichtbar sind. In den meisten Fällen können Sie mit einer Clientbibliothek Aufrufe von Google APIs einrichten, z. B. beim Aufrufen der Drive Files API.
Im OAuth 2.0 Playground können Sie alle Google APIs ausprobieren und sich ihre Bereiche ansehen.
Beispiele für HTTP-GET
Ein Aufruf des Endpunkts
drive.files (Drive Files API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen: Sie müssen Ihr 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 Befehlszeilenanwendung curl testen. Hier ein Beispiel, in dem die HTTP-Header-Option verwendet wird (bevorzugt):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Alternativ können Sie auch die Option „Abfragestringparameter“ verwenden:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
JavaScript-Beispielcode
Im folgenden Code-Snippet wird gezeigt, wie Sie mit CORS (Cross-Origin Resource Sharing) eine Anfrage an eine Google API senden. In diesem Beispiel wird die Google APIs-Clientbibliothek für JavaScript nicht verwendet. Auch wenn Sie die Clientbibliothek nicht verwenden, hilft Ihnen der Leitfaden zur CORS-Unterstützung in der Dokumentation dieser Bibliothek wahrscheinlich, diese Anfragen besser zu verstehen.
In diesem Code-Snippet steht die Variable access_token für das Token, das Sie erhalten haben, um im Namen des autorisierten Nutzers API-Anfragen zu senden. Im vollständigen Beispiel wird gezeigt, wie dieses Token im lokalen Speicher des Browsers gespeichert und bei einer API-Anfrage abgerufen wird.
var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/drive/v3/about?fields=user&' + 'access_token=' + params['access_token']); xhr.onreadystatechange = function (e) { console.log(xhr.response); }; xhr.send(null);
Vollständiges Beispiel
OAuth 2.0-Endpunkte
In diesem Codebeispiel wird gezeigt, wie der OAuth 2.0-Ablauf in JavaScript abgeschlossen wird, ohne die Google APIs-Clientbibliothek für JavaScript zu verwenden. Der Code ist für eine HTML-Seite mit einer Schaltfläche zum Testen einer API-Anfrage. Wenn Sie auf die Schaltfläche klicken, wird im Code geprüft, ob die Seite ein API-Zugriffstoken im lokalen Speicher Ihres Browsers gespeichert hat. Andernfalls wird die API-Anfrage ausgeführt. Andernfalls wird der OAuth 2.0-Vorgang gestartet.
Für den OAuth 2.0-Vorgang werden auf der Seite die folgenden Schritte ausgeführt:
- Der Nutzer wird zum OAuth 2.0-Server von Google weitergeleitet, der Zugriff auf die Bereiche
https://www.googleapis.com/auth/drive.metadata.readonlyundhttps://www.googleapis.com/auth/calendar.readonlyanfordert. - Nachdem der Nutzer einem oder mehreren angeforderten Bereichen Zugriff gewährt oder diesen abgelehnt hat, wird er zur ursprünglichen Seite weitergeleitet, auf der das Zugriffstoken aus dem String der Fragment-ID geparst wird.
- Auf der Seite wird geprüft, für welche Bereiche der Nutzer der Anwendung Zugriff gewährt hat.
Wenn der Nutzer Zugriff auf die angeforderten Bereiche gewährt hat, wird auf der Seite das Zugriffstoken verwendet, um die Beispiel-API-Anfrage zu senden.
In der API-Anfrage wird die Methode
about.getder Drive API aufgerufen, um Informationen zum Google Drive-Konto des autorisierten Nutzers abzurufen.- Wenn die Anfrage erfolgreich ausgeführt wird, wird die API-Antwort in der Debug-Konsole des Browsers protokolliert.
Sie können den Zugriff auf die App über die Seite Berechtigungen für Ihr Google-Konto widerrufen. Die App wird als OAuth 2.0-Demo für Google API Docs aufgeführt.
Wenn Sie diesen Code lokal ausführen möchten, müssen Sie Werte für die Variablen YOUR_CLIENT_ID und YOUR_REDIRECT_URI festlegen, die Ihren Anmeldedaten entsprechen. Die Variable YOUR_REDIRECT_URI sollte auf dieselbe URL festgelegt sein, über die die Seite ausgeliefert wird. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, die Sie in der API Console Credentials pagekonfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, wird der Fehler redirect_uri_mismatch ausgegeben. Außerdem muss für Ihr Projekt die entsprechende API für diese Anfrage aktiviert sein.
<html><head></head><body>
<script>
var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
// Parse query string to see if page request is coming from OAuth 2.0 server.
var fragmentString = location.hash.substring(1);
var params = {};
var regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(fragmentString)) {
params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}
if (Object.keys(params).length > 0 && params['state']) {
if (params['state'] == localStorage.getItem('state')) {
localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
trySampleRequest();
} else {
console.log('State mismatch. Possible CSRF attack');
}
}
// Function to generate a random state value
function generateCryptoRandomState() {
const randomValues = new Uint32Array(2);
window.crypto.getRandomValues(randomValues);
// Encode as UTF-8
const utf8Encoder = new TextEncoder();
const utf8Array = utf8Encoder.encode(
String.fromCharCode.apply(null, randomValues)
);
// Base64 encode the UTF-8 data
return btoa(String.fromCharCode.apply(null, utf8Array))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
// If there's an access token, try an API request.
// Otherwise, start OAuth 2.0 flow.
function trySampleRequest() {
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
if (params && params['access_token']) {
// User authorized the request. Now, check which scopes were granted.
if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
// User authorized read-only Drive activity permission.
// Calling the APIs, etc.
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/drive/v3/about?fields=user&' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
if (xhr.readyState === 4 && xhr.status === 200) {
console.log(xhr.response);
} else if (xhr.readyState === 4 && xhr.status === 401) {
// Token invalid, so prompt for user permission.
oauth2SignIn();
}
};
xhr.send(null);
}
else {
// User didn't authorize read-only Drive activity permission.
// Update UX and application accordingly
console.log('User did not authorize read-only Drive activity permission.');
}
// Check if user authorized Calendar read permission.
if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
// User authorized Calendar read permission.
// Calling the APIs, etc.
console.log('User authorized Calendar read permission.');
}
else {
// User didn't authorize Calendar read permission.
// Update UX and application accordingly
console.log('User did not authorize Calendar read permission.');
}
} else {
oauth2SignIn();
}
}
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauth2SignIn() {
// create random state value and store in local storage
var state = generateCryptoRandomState();
localStorage.setItem('state', state);
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create element to open OAuth 2.0 endpoint in new window.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': YOUR_CLIENT_ID,
'redirect_uri': YOUR_REDIRECT_URI,
'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
'state': state,
'include_granted_scopes': 'true',
'response_type': 'token'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
</script>
<button onclick="trySampleRequest();">Try sample request</button>
</body></html>Validierungsregeln für JavaScript-Quellen
Google wendet die folgenden Validierungsregeln auf JavaScript-Quellen an, um Entwicklern zu helfen, ihre Anwendungen zu schützen. Ihre JavaScript-Quellen müssen diesen Regeln entsprechen. Die Definitionen für Domain, Host und Schema finden Sie unter RFC 3986 Abschnitt 3.
| Validierungsregeln | |
|---|---|
| Schema |
JavaScript-Quellen müssen das HTTPS-Schema verwenden, nicht nur HTTP. Localhost-URIs (einschließlich localhost-IP-Adressen-URIs) sind von dieser Regel ausgenommen. |
| Moderator:in |
Hosts dürfen keine Roh-IP-Adressen sein. Localhost-IP-Adressen sind von dieser Regel ausgenommen. |
| Domain |
“googleusercontent.com” sein.goo.gl) enthalten, es sei denn, die Domain gehört der App. |
| Userinfo |
JavaScript-Quellen dürfen die untergeordnete Komponente „userinfo“ nicht enthalten. |
| Pfad |
JavaScript-Ursprünge dürfen keine Pfadkomponente enthalten. |
| Abfrage |
JavaScript-Quellen dürfen die Abfragekomponente nicht enthalten. |
| Fragment |
JavaScript-Quellen dürfen die Fragmentkomponente nicht enthalten. |
| Zeichen |
JavaScript-Quellen dürfen bestimmte Zeichen nicht enthalten, darunter:
|
Inkrementelle Autorisierung
Im OAuth 2.0-Protokoll fordert Ihre App die Autorisierung für den Zugriff auf Ressourcen an, die durch Bereiche gekennzeichnet sind. Aus Gründen der Nutzerfreundlichkeit sollten Sie die Autorisierung für Ressourcen immer dann anfordern, wenn Sie sie benötigen. Dazu unterstützt der Autorisierungsserver von Google die inkrementelle Autorisierung. Mit dieser Funktion können Sie nach Bedarf Zugriffsbereiche anfordern. Wenn der Nutzer die Berechtigung für den neuen Bereich gewährt, wird ein Autorisierungscode zurückgegeben, der gegen ein Token eingetauscht werden kann, das alle Bereiche enthält, die der Nutzer dem Projekt gewährt hat.
Eine App, mit der Nutzer Musiktitel samplen und Mixe erstellen können, benötigt beispielsweise bei der Anmeldung möglicherweise nur sehr wenige Ressourcen, vielleicht nur den Namen der Person, die sich anmeldet. Zum Speichern eines fertigen Mixes ist jedoch Zugriff auf sein Google Drive erforderlich. Die meisten Nutzer würden es für selbstverständlich halten, wenn sie nur dann um Zugriff auf ihr Google Drive-Konto gebeten würden, wenn die App ihn tatsächlich benötigt.
In diesem Fall kann die App bei der Anmeldung die Bereiche openid und profile anfordern, um eine grundlegende Anmeldung durchzuführen, und dann später bei der ersten Anfrage den Bereich https://www.googleapis.com/auth/drive.file, um einen Mix zu speichern.
Für ein Zugriffstoken, das über eine inkrementelle Autorisierung abgerufen wurde, gelten die folgenden Regeln:
- Das Token kann verwendet werden, um auf Ressourcen zuzugreifen, die den Bereichen entsprechen, die in die neue kombinierte Autorisierung übernommen wurden.
- Wenn Sie das Aktualisierungstoken für die kombinierte Autorisierung verwenden, um ein Zugriffstoken zu erhalten, steht das Zugriffstoken für die kombinierte Autorisierung und kann für jeden der in der Antwort enthaltenen
scope-Werte verwendet werden. - Die kombinierte Autorisierung umfasst alle Bereiche, die der Nutzer dem API-Projekt gewährt hat, auch wenn die Berechtigungen von verschiedenen Clients angefordert wurden. Wenn ein Nutzer beispielsweise über den Desktop-Client einer Anwendung Zugriff auf einen Bereich gewährt und dann über einen mobilen Client einen weiteren Bereich für dieselbe Anwendung gewährt hat, umfasst die kombinierte Autorisierung beide Bereiche.
- Wenn Sie ein Token widerrufen, das eine kombinierte Autorisierung darstellt, wird der Zugriff auf alle Bereiche dieser Autorisierung im Namen des zugehörigen Nutzers gleichzeitig widerrufen.
In den folgenden Codebeispielen wird gezeigt, wie einem vorhandenen Zugriffstoken Bereiche hinzugefügt werden. So müssen Sie in Ihrer App nicht mehrere Zugriffstokens verwalten.
OAuth 2.0-Endpunkte
Wenn Sie einem vorhandenen Zugriffstoken Bereiche hinzufügen möchten, fügen Sie den Parameter include_granted_scopes in Ihre Anfrage an den OAuth 2.0-Server von Google ein.
Das folgende Code-Snippet zeigt, wie das geht. Im Snippet wird davon ausgegangen, dass Sie die Bereiche, für die Ihr Zugriffstoken gültig ist, im lokalen Speicher des Browsers gespeichert haben. Im vollständigen Beispiel wird eine Liste der Zugriffsbereiche gespeichert, für die das Zugriffstoken gültig ist. Dazu wird die Property oauth2-test-params.scope im lokalen Speicher des Browsers festgelegt.
Im Snippet werden die Bereiche, für die das Zugriffstoken gültig ist, mit dem Bereich verglichen, den Sie für eine bestimmte Abfrage verwenden möchten. Wenn der Zugriffsbereich nicht durch das Zugriffstoken abgedeckt ist, wird der OAuth 2.0-Ablauf gestartet.
Hier ist die oauth2SignIn-Funktion dieselbe wie in Schritt 2 (und wird später im vollständigen Beispiel verwendet).
var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'; var params = JSON.parse(localStorage.getItem('oauth2-test-params')); var current_scope_granted = false; if (params.hasOwnProperty('scope')) { var scopes = params['scope'].split(' '); for (var s = 0; s < scopes.length; s++) { if (SCOPE == scopes[s]) { current_scope_granted = true; } } } if (!current_scope_granted) { oauth2SignIn(); // This function is defined elsewhere in this document. } else { // Since you already have access, you can proceed with the API request. }
Token widerrufen
In einigen Fällen möchte ein Nutzer den einer Anwendung erteilten Zugriff widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen finden Sie im Hilfeartikel Websites und Apps von Drittanbietern mit Zugriff auf Ihr Konto im Abschnitt Zugriff auf Websites oder Apps entfernen.
Es ist auch möglich, dass eine Anwendung den ihr gewährten Zugriff programmatisch widerruft. Der programmatische Widerruf ist wichtig, wenn ein Nutzer sein Abo kündigt, eine App entfernt oder sich die von einer App benötigten API-Ressourcen erheblich geändert haben. Mit anderen Worten: Ein Teil des Entfernungsvorgangs kann eine API-Anfrage umfassen, um sicherzustellen, dass die zuvor der Anwendung erteilten Berechtigungen entfernt werden.
OAuth 2.0-Endpunkte
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 hinzu:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}Das Token kann ein Zugriffs- oder Aktualisierungstoken sein. Wenn es sich bei dem Token um ein Zugriffstoken handelt und es ein entsprechendes Aktualisierungstoken hat, wird auch das Aktualisierungstoken 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.
Im folgenden JavaScript-Snippet wird gezeigt, wie ein Token in JavaScript widerrufen wird, ohne die Clientbibliothek für Google APIs für JavaScript zu verwenden. Da der OAuth 2.0-Endpunkt von Google zum Widerrufen von Tokens keine CORS-Unterstützung (Cross-Origin Resource Sharing) bietet, wird im Code ein Formular erstellt und an den Endpunkt gesendet, anstatt die Anfrage mit der XMLHttpRequest()-Methode zu senden.
function revokeAccess(accessToken) { // Google's OAuth 2.0 endpoint for revoking access tokens. var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke'; // Create <form> element to use to POST data to the OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'post'); form.setAttribute('action', revokeTokenEndpoint); // Add access token to the form so it is set as value of 'token' parameter. // This corresponds to the sample curl request, where the URL is: // https://oauth2.googleapis.com/revoke?token={token} var tokenField = document.createElement('input'); tokenField.setAttribute('type', 'hidden'); tokenField.setAttribute('name', 'token'); tokenField.setAttribute('value', accessToken); form.appendChild(tokenField); // Add form to page and submit it to actually revoke the token. document.body.appendChild(form); form.submit(); }
Produktübergreifenden Kontoschutz implementieren
Sie sollten außerdem den Kontoübergreifenden Schutz implementieren, indem Sie den Kontoübergreifenden Schutzdienst von Google verwenden. Mit diesem Dienst können Sie Benachrichtigungen zu Sicherheitsereignissen abonnieren, die Ihre Anwendung über wichtige Änderungen am Nutzerkonto informieren. Je nachdem, wie Sie auf Ereignisse reagieren möchten, können Sie dann Maßnahmen ergreifen.
Beispiele für Ereignistypen, die vom geräteübergreifenden Schutzdienst von Google an Ihre App gesendet werden:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
Auf der Seite Nutzerkonten mit dem produktübergreifenden Kontoschutz schützen finden Sie weitere Informationen zur Implementierung des produktübergreifenden Kontoschutzes und eine vollständige Liste der verfügbaren Ereignisse.