Mit der JavaScript-Bibliothek google.accounts.oauth2 können Sie die Nutzereinwilligung einholen und ein Zugriffstoken für die Arbeit mit Nutzerdaten anfordern. Sie basiert auf dem impliziten OAuth 2.0-Zustimmungsvorgang und ermöglicht es dir, Google APIs direkt über REST und CORS aufzurufen oder die Google APIs-Clientbibliothek für JavaScript (auch gapi.client genannt) für einen einfachen, flexiblen Zugriff auf unsere komplexeren APIs zu verwenden.
Bevor über einen Browser auf geschützte Nutzerdaten zugegriffen wird, lösen Nutzer auf Ihrer Website die webbasierte Kontoauswahl sowie die Anmelde- und Einwilligungsprozesse von Google aus. Schließlich stellen die OAuth-Server von Google ein Zugriffstoken aus und geben es an Ihre Webanwendung zurück.
Im tokenbasierten Autorisierungsmodell müssen keine Aktualisierungstokens pro Nutzer auf Ihrem Back-End-Server gespeichert werden.
Es wird empfohlen, anstelle der im vorherigen Leitfaden zu OAuth 2.0 für clientseitige Webanwendungen beschriebenen Methoden die hier beschriebene Vorgehensweise zu verwenden.
Einrichtung
Suchen oder erstellen Sie eine Client-ID. Folgen Sie dazu der Anleitung unter Google API-Client-ID abrufen. Als Nächstes fügen Sie die Clientbibliothek den Seiten Ihrer Website hinzu, die Google APIs aufrufen. Initialisieren Sie zum Schluss den Token-Client. In der Regel erfolgt dies im onload-Handler der Clientbibliothek.
Tokenclient initialisieren
Rufen Sie initTokenClient() auf, um einen neuen Tokenclient mit der Client-ID Ihrer Webanwendung zu initialisieren. Optional können Sie eine Liste mit einem oder mehreren Bereichen angeben, auf die der Nutzer zugreifen muss:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
callback: (response) => {
...
},
});
OAuth 2.0-Tokenvorgang auslösen
Verwenden Sie die Methode requestAccessToken(), um den UX-Vorgang für Tokens auszulösen und ein Zugriffstoken abzurufen. Google fordert den Nutzer auf, Folgendes zu tun:
- Wählen Sie das Konto aus,
- melden Sie sich im Google-Konto an, falls Sie noch nicht angemeldet sind.
- die Einwilligung für Ihre Webanwendung zum Zugriff auf jeden angeforderten Bereich zu erteilen.
Eine Nutzergeste löst den Tokenfluss aus: <button onclick="client.requestAccessToken();">Authorize me</button>
Google gibt dann eine TokenResponse zurück, die ein Zugriffstoken und eine Liste der Bereiche enthält, denen der Nutzer Zugriff gewährt hat, oder einen Fehler an den Callback-Handler.
Nutzer können die Fenster für die Kontoauswahl oder die Anmeldung schließen. In diesem Fall wird Ihre Callback-Funktion nicht aufgerufen.
Umgang mit der Einwilligung
Das Design und die Nutzererfahrung für Ihre App sollten erst nach eingehender Überprüfung der OAuth 2.0-Richtlinien von Google implementiert werden. Diese Richtlinien decken unter anderem das Arbeiten mit mehreren Bereichen ab, wann und wie mit Nutzereinwilligungen umgegangen werden soll.
Die inkrementelle Autorisierung ist eine Richtlinien- und Anwendungsdesignmethode, die verwendet wird, um Zugriff auf Ressourcen unter Verwendung von Bereichen anzufordern, und zwar nur bei Bedarf und nicht im Voraus und gleichzeitig. Nutzer können die Freigabe der einzelnen Ressourcen, die von Ihrer App angefordert werden, genehmigen oder ablehnen. Dies wird als detaillierte Berechtigungen bezeichnet.
Während dieses Vorgangs fordert Google die Nutzer zur Einwilligung auf. Dabei werden alle angeforderten Bereiche einzeln aufgelistet. Die Nutzer wählen dann die Ressourcen aus, die für die Anwendung freigegeben werden sollen. Schließlich ruft Google Ihre Callback-Funktion auf, um ein Zugriffstoken und vom Nutzer genehmigte Bereiche zurückzugeben. Ihre App verarbeitet dann die verschiedenen möglichen Ergebnisse sicher und mit detaillierten Berechtigungen.
Inkrementelle Autorisierung
Für Webanwendungen wird in den folgenden beiden allgemeinen Szenarien die inkrementelle Autorisierung mithilfe von
- Eine einseitige Ajax-Anwendung, die häufig
XMLHttpRequestmit dynamischem Zugriff auf Ressourcen verwendet. - Mehrere Webseiten, Ressourcen werden separat verwaltet und pro Seite verwaltet.
Diese beiden Szenarien dienen der Veranschaulichung von Designüberlegungen und -methoden. Sie sind jedoch keine umfassenden Empfehlungen zum Einbinden der Nutzereinwilligung in Ihre App. Für reale Anwendungen können diese Methoden variieren oder kombiniert werden.
Ajax Amsterdam
Wenn Sie die inkrementelle Autorisierung für Ihre Anwendung unterstützen möchten, rufen Sie requestAccessToken() mehrmals auf und verwenden Sie den Parameter scope des OverridableTokenClientConfig-Objekts, um einzelne Bereiche bei Bedarf und nur bei Bedarf anzufordern. In diesem Beispiel werden Ressourcen erst angefordert und sichtbar, nachdem eine Nutzergeste einen minimierten Inhaltsbereich maximiert hat.
| Ajax-Anwendung |
|---|
Initialisieren Sie den Tokenclient beim Seitenaufbau:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: "onTokenResponse",
});
Über Nutzergesten die Einwilligung anfordern und Zugriffstokens erhalten. Klicken Sie zum Öffnen auf „+“:
Dokumente zum LesenZuletzt verwendete Dokumente anzeigen
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/documents.readonly'
})
);
Anstehende VeranstaltungenKalenderinformationen anzeigen
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/calendar.readonly'
})
);
FotokarussellFotos anzeigen
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
})
);
|
Jeder Aufruf von requestAccessToken löst einen Nutzereinwilligungszeitpunkt aus. Ihre App hat dann nur Zugriff auf die Ressourcen, die für den Bereich erforderlich sind, den der Nutzer erweitern möchte. Dadurch wird die Ressourcenfreigabe durch die Nutzerauswahl eingeschränkt.
Mehrere Webseiten
Beim Entwerfen für die inkrementelle Autorisierung werden mehrere Seiten verwendet, um nur die Bereiche anzufordern, die zum Laden einer Seite erforderlich sind. Dadurch wird die Komplexität verringert und die Notwendigkeit mehrerer Aufrufe zum Einholen der Nutzereinwilligung und zum Abrufen eines Zugriffstokens verringert.
| Mehrseitige App | ||||||||
|---|---|---|---|---|---|---|---|---|
|
Jede Seite fordert den erforderlichen Bereich an und ruft durch Aufrufen von initTokenClient() und requestAccessToken() zum Laden ein Zugriffstoken ab. In diesem Szenario werden einzelne Webseiten verwendet, um Nutzerfunktionen und Ressourcen klar nach Bereich zu trennen. In der Praxis können einzelne Seiten mehrere verwandte Bereiche anfordern.
Detaillierte Berechtigungen
Detaillierte Berechtigungen werden in allen Szenarien gleich behandelt. Nachdem requestAccessToken() die Callback-Funktion aufgerufen und ein Zugriffstoken zurückgegeben wurde, prüfen Sie mit hasGrantedAllScopes() oder hasGrantedAnyScope(), ob der Nutzer die angeforderten Bereiche genehmigt hat. Beispiel:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly \
https://www.googleapis.com/auth/documents.readonly \
https://www.googleapis.com/auth/photoslibrary.readonly',
callback: (tokenResponse) => {
if (tokenResponse && tokenResponse.access_token) {
if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
'https://www.googleapis.com/auth/photoslibrary.readonly')) {
// Look at pictures
...
}
if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
'https://www.googleapis.com/auth/calendar.readonly',
'https://www.googleapis.com/auth/documents.readonly')) {
// Meeting planning and review documents
...
}
}
},
});
Alle zuvor angenommenen Erteilungen aus vorherigen Sitzungen oder Anfragen werden ebenfalls in die Antwort aufgenommen. Ein Datensatz der Nutzereinwilligung wird pro Nutzer und Client-ID erstellt und bleibt über mehrere Aufrufe von initTokenClient() oder requestAccessToken() bestehen. Standardmäßig ist die Nutzereinwilligung nur erforderlich, wenn ein Nutzer Ihre Website zum ersten Mal besucht und einen neuen Bereich anfordert. Sie kann jedoch bei jedem Seitenaufbau mit prompt=consent in Token Client-Konfigurationsobjekten angefordert werden.
Mit Tokens arbeiten
Im Token-Modell wird kein Zugriffstoken vom Betriebssystem oder Browser gespeichert. Stattdessen wird beim Seitenaufbau zuerst ein neues Token abgerufen. Anschließend wird durch eine Nutzergeste, z. B. durch das Drücken einer Schaltfläche, ein Aufruf von requestAccessToken() ausgelöst.
REST und CORS mit Google APIs verwenden
Ein Zugriffstoken kann verwendet werden, um authentifizierte Anfragen an Google APIs mithilfe von REST und CORS zu stellen. Dadurch können sich Nutzer anmelden, ihre Einwilligung erteilen, Google ein Zugriffstoken ausstellen und Ihre Website mit den Daten des Nutzers arbeiten.
In diesem Beispiel werden die anstehenden Kalendertermine der angemeldeten Nutzer mit dem von tokenRequest() zurückgegebenen Zugriffstoken angezeigt:
var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();
Weitere Informationen finden Sie unter Mit CORS auf Google APIs zugreifen.
Im nächsten Abschnitt geht es um die einfache Integration komplexerer APIs.
Mit der JavaScript-Bibliothek der Google APIs arbeiten
Der Token-Client funktioniert mit der Google API-Clientbibliothek für JavaScript. Siehe folgendes Code-Snippet.
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
callback: (tokenResponse) => {
if (tokenResponse && tokenResponse.access_token) {
gapi.client.setApiKey('YOUR_API_KEY');
gapi.client.load('calendar', 'v3', listUpcomingEvents);
}
},
});
function listUpcomingEvents() {
gapi.client.calendar.events.list(...);
}
Ablauf des Tokens
Zugriffstokens haben eine kurze Lebensdauer. Wenn das Zugriffstoken vor dem Ende der Nutzersitzung abläuft, fordern Sie ein neues Token an. Rufen Sie dazu requestAccessToken() über ein nutzergesteuertes Ereignis wie einen Tastendruck auf.
Einwilligung mithilfe eines Zugriffstokens widerrufen
Rufen Sie die Methode google.accounts.oauth2.revoke auf, um die Nutzereinwilligung und den Zugriff auf Ressourcen für alle Bereiche zu entfernen, die Ihrer App gewährt wurden. Zum Widerrufen dieser Berechtigung ist ein gültiges Zugriffstoken erforderlich:
google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
console.log(done);
console.log(done.successful);
console.log(done.error);
console.log(done.error_description);
});