Tokenmodell verwenden

Mit der google.accounts.oauth2-JavaScript-Bibliothek können Sie die Nutzereinwilligung einholen und ein Zugriffstoken für die Verarbeitung von Nutzerdaten abrufen. Sie basiert auf dem OAuth 2.0-Vorgang für die implizite Autorisierung und ermöglicht es Ihnen, Google APIs entweder direkt über REST und CORS aufzurufen oder unsere Google API-Clientbibliothek für JavaScript (auch als gapi.client bezeichnet) für einfachen, flexiblen Zugriff auf unsere komplexeren APIs zu verwenden.

Bevor Nutzer auf Ihrer Website über einen Browser auf geschützte Nutzerdaten zugreifen, lösen sie die webbasierte Kontoauswahl, Anmeldung und Einwilligung von Google aus. Anschließend geben die OAuth-Server von Google ein Zugriffstoken für Ihre Webanwendung aus.

Beim tokenbasierten Autorisierungsmodell müssen keine pro Nutzer gültigen Aktualisierungstokens auf Ihrem Backend-Server gespeichert werden.

Wir empfehlen, den hier beschriebenen Ansatz anstelle der Methoden zu verwenden, die im älteren Leitfaden OAuth 2.0 für clientseitige Webanwendungen beschrieben werden.

Einrichtung

Rufen Sie eine Client-ID ab oder erstellen Sie eine, indem Sie die Schritte im Leitfaden Google API-Client-ID abrufen ausführen. Fügen Sie die Clientbibliothek den Seiten Ihrer Website hinzu, auf denen Google APIs aufgerufen werden. Initialisieren Sie abschließend den Token-Client. Normalerweise geschieht dies im onload-Handler der Clientbibliothek.

Token-Client initialisieren

Rufe initTokenClient() auf, um einen neuen Token-Client mit der Client-ID deiner Webanwendung zu initialisieren. Optional kannst du 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-Token-Flow auslösen

Verwende die Methode requestAccessToken(), um den UX-Token-Flow auszulösen und ein Zugriffstoken abzurufen. Google fordert den Nutzer auf, Folgendes zu tun:

• Wählen Sie das Konto aus.
• Melden Sie sich in Ihrem Google-Konto an, falls Sie noch nicht angemeldet sind.
• Sie müssen Ihre Web-App berechtigen, auf jeden angeforderten Umfang zuzugreifen.

Eine Nutzergeste löst den Token-Flow aus: <button onclick="client.requestAccessToken();">Authorize me</button>

Google gibt dann ein TokenResponse mit einem Zugriffstoken und einer Liste der Bereiche zurück, für die der Nutzer Zugriff gewährt hat, oder einen Fehler an Ihren Callback-Handler zurück.

Nutzer können die Kontoauswahl oder die Anmeldefenster schließen. In diesem Fall wird Ihre Rückruffunktion nicht aufgerufen.

Umgang mit Einwilligungen

Das Design und die Nutzerfreundlichkeit Ihrer App sollten erst nach einer gründlichen Prüfung der OAuth 2.0-Richtlinien von Google implementiert werden. Diese Richtlinien decken unter anderem die Verwendung mehrerer Gültigkeitsbereiche und die Frage ab, wann und wie die Einwilligung der Nutzer zu behandeln ist.

Die inkrementelle Autorisierung ist eine Richtlinie und App-Designmethode, mit der der Zugriff auf Ressourcen mithilfe von Bereichen nur bei Bedarf angefordert wird, anstatt vorab und auf einmal. Nutzer können die Freigabe der einzelnen von Ihrer App angeforderten Ressourcen genehmigen oder ablehnen. Dies wird als detaillierte Berechtigungen bezeichnet.

Während dieses Vorgangs fordert Google die Nutzereinwilligung an und listet jeden angeforderten Umfang einzeln auf. Die Nutzer wählen die Ressourcen aus, die für Ihre App freigegeben werden sollen. Anschließend ruft Google Ihre Callback-Funktion auf, um ein Zugriffstoken und die vom Nutzer genehmigten Bereiche zurückzugeben. Ihre App kann dann die verschiedenen Ergebnisse, die mit detaillierten Berechtigungen möglich sind, sicher verarbeiten.

Es gibt jedoch Ausnahmen. Bei Google Workspace Enterprise-Apps mit domainweiter Übertragung von Befugnissen oder Apps, die als Vertrauenswürdig gekennzeichnet sind, wird der Bildschirm zur Einwilligung in die detaillierten Berechtigungen übersprungen. Bei diesen Apps wird Nutzern der Bildschirm mit der detaillierten Einwilligung in Berechtigungen nicht angezeigt. Stattdessen erhält Ihre App entweder alle angeforderten Bereiche oder keinen.

Weitere Informationen finden Sie unter Detaillierte Berechtigungen verwenden.

Inkrementelle Autorisierung

Für Webanwendungen zeigen die folgenden beiden allgemeinen Szenarien die inkrementelle Autorisierung mit folgenden Methoden:

• Eine Single-Page-Ajax-Anwendung, die häufig XMLHttpRequest mit dynamischem Zugriff auf Ressourcen verwendet.
• Mehrere Webseiten: Ressourcen werden getrennt und pro Seite verwaltet.

Diese beiden Szenarien sollen Designüberlegungen und -methoden veranschaulichen, sind aber keine umfassenden Empfehlungen dazu, wie Sie die Einwilligung in Ihre App einbinden. In der Praxis werden in Apps möglicherweise eine Variante oder eine Kombination dieser Techniken verwendet.

Ajax

Sie können Ihrer App die Unterstützung für die inkrementelle Autorisierung hinzufügen, indem Sie mehrere requestAccessToken()-Aufrufe ausführen und den Parameter scope des OverridableTokenClientConfig-Objekts verwenden, um einzelne Bereiche nur dann anzufordern, wenn sie benötigt werden. In diesem Beispiel werden Ressourcen erst angefordert und angezeigt, nachdem ein Nutzer einen minimierten Inhaltsbereich maximiert hat.

        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
      

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/documents.readonly'
             })
           );
        

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/calendar.readonly'
             })
           );
        

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
             })
           );
        

Jeder Aufruf von requestAccessToken löst eine Einwilligung des Nutzers aus. Ihre App hat nur Zugriff auf die Ressourcen, die für den Bereich erforderlich sind, den ein Nutzer maximiert. So wird die Freigabe von Ressourcen durch die Auswahl des Nutzers eingeschränkt.

Mehrere Webseiten

Bei der schrittweisen Autorisierung werden mehrere Seiten verwendet, um nur die Berechtigungen anzufordern, die zum Laden einer Seite erforderlich sind. Dadurch wird die Komplexität reduziert und es ist nicht mehr erforderlich, mehrere Aufrufe auszuführen, um die Nutzereinwilligung einzuholen und ein Zugriffstoken abzurufen.

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
          

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
          

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();
          

Jede Seite fordert den erforderlichen Umfang an und ruft beim Laden initTokenClient() und requestAccessToken() auf, um ein Zugriffstoken zu erhalten. In diesem Szenario werden einzelne Webseiten verwendet, um Nutzerfunktionen und Ressourcen nach Umfang klar voneinander zu trennen. In der Praxis können für einzelne Seiten mehrere zugehörige Bereiche angefordert werden.

Detaillierte Berechtigungen

Detaillierte Berechtigungen werden in allen Szenarien gleich behandelt. Nachdem requestAccessToken() deine Rückruffunktion aufgerufen und ein Zugriffstoken zurückgegeben hat, prüfe, ob der Nutzer die angeforderten Bereiche mit hasGrantedAllScopes() oder hasGrantedAnyScope() 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 akzeptierten Bewilligungen aus früheren Sitzungen oder Anfragen werden ebenfalls in die Antwort einbezogen. Pro Nutzer und Client-ID wird ein Eintrag zur Nutzereinwilligung gespeichert, der über mehrere Aufrufe von initTokenClient() oder requestAccessToken() hinweg erhalten bleibt. Standardmäßig ist die Nutzereinwilligung nur erforderlich, wenn ein Nutzer zum ersten Mal Ihre Website besucht und einen neuen Gültigkeitsbereich anfordert. Sie kann aber bei jedem Seitenaufbau mithilfe von prompt=consent in Token-Client-Konfigurationsobjekten angefordert werden.

Mit Tokens arbeiten

Beim Token-Modell wird ein Zugriffstoken nicht vom Betriebssystem oder Browser gespeichert. Stattdessen wird beim Laden der Seite oder später durch Auslösen eines Aufrufs von requestAccessToken() über eine Nutzergeste wie das Drücken einer Schaltfläche ein neues Token abgerufen.

REST und CORS mit Google APIs verwenden

Mit einem Zugriffstoken können authentifizierte Anfragen an Google APIs mithilfe von REST und CORS gesendet werden. So 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 des angemeldeten Nutzers 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 CORS zum Zugriff auf Google APIs verwenden.

Im nächsten Abschnitt erfahren Sie, wie Sie komplexere APIs ganz einfach einbinden.

Mit der JavaScript-Bibliothek von Google APIs arbeiten

Der Token-Client funktioniert mit der Google API-Clientbibliothek für JavaScript. Siehe Code-Snippet unten.

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 von Natur aus eine kurze Lebensdauer. Wenn das Zugriffstoken vor dem Ende der Sitzung des Nutzers abläuft, rufe requestAccessToken() über ein vom Nutzer ausgelöstes Ereignis wie das Drücken einer Schaltfläche auf, um ein neues Token abzurufen.

Einwilligung mit einem Zugriffstoken widerrufen

Rufen Sie die Methode google.accounts.oauth2.revoke auf, um die Nutzereinwilligung und den Zugriff auf Ressourcen für alle Bereiche aufzuheben, 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);
  });