Codemodell verwenden

Mit der Google Identity Services-Bibliothek können Nutzer entweder über ein browserbasiertes Pop-up oder eine Weiterleitung einen Autorisierungscode von Google anfordern. Dadurch wird ein sicherer OAuth 2.0-Ablauf gestartet, der zu einem Zugriffstoken führt, mit dem Google APIs im Namen eines Nutzers aufgerufen werden.

Zusammenfassung des OAuth 2.0-Vorgangs mit Autorisierungscode:

• Der Google-Kontoinhaber fordert über einen Browser mit einer Geste wie einem Klick auf eine Schaltfläche einen Autorisierungscode von Google an.
• Google antwortet und sendet einen eindeutigen Autorisierungscode entweder an einen Rückruf in Ihrer JavaScript-Web-App, die im Browser des Nutzers ausgeführt wird, oder ruft Ihren Autorisierungscode-Endpunkt direkt über eine Browserweiterleitung auf.
• Ihre Backend-Plattform hostet einen Autorisierungscode-Endpunkt und empfängt den Code. Nach der Validierung wird dieser Code über eine Anfrage an den Token-Endpunkt von Google gegen Zugriffs- und Aktualisierungstokens für den jeweiligen Nutzer eingetauscht.
• Google validiert den Autorisierungscode, bestätigt, dass die Anfrage von deiner sicheren Plattform stammt, stellt Zugriffs- und Aktualisierungstokens aus und gibt die Tokens zurück, indem der Anmeldeendpunkt aufgerufen wird, der auf deiner Plattform gehostet wird.
• Ihr Anmeldeendpunkt empfängt die Zugriffs- und Aktualisierungstokens und speichert das Aktualisierungstoken sicher für die spätere Verwendung.

Wichtig :Auf Ihrem Backend-Server tauschen Sie einen Autorisierungscode gegen Aktualisierungs- und Zugriffstokens aus, indem Sie den Token-Endpunkt von Google aufrufen.

Vorbereitung

Folgen Sie der Anleitung unter Einrichtung, um den OAuth-Zustimmungsbildschirm zu konfigurieren, eine Client-ID abzurufen und die Clientbibliothek zu laden.

Code-Client initialisieren

Mit der Methode google.accounts.oauth2.initCodeClient() wird ein Codeclient initialisiert.

Pop-up- oder Weiterleitungsmodus

Sie können einen Autorisierungscode entweder über den Nutzerfluss im Modus Weiterleitung oder Pop-up freigeben. Im Weiterleitungsmodus hostest du einen OAuth2-Autorisierungsendpunkt auf deinem Server. Google leitet den User-Agent auf diesen Endpunkt weiter und gibt den Autorisierungscode als URL-Parameter weiter. Für den Pop-up-Modus definieren Sie einen JavaScript-Callback-Handler, der den Autorisierungscode an Ihren Server sendet. Mit dem Pop-up-Modus können Sie eine nahtlose Nutzererfahrung bieten, ohne dass Besucher Ihre Website verlassen müssen.

So initialisieren Sie einen Client für:

• Leite den UX-Flow weiter, setze ux_mode auf redirect und den Wert von redirect_uri auf den Autorisierungscode-Endpunkt deiner Plattform. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in der API Console konfiguriert haben. Außerdem muss er unseren Gültigkeitsregeln für Weiterleitungs-URIs entsprechen.

• Für den UX-Flow des Pop-ups legen Sie ux_mode auf popup und den Wert von callback auf den Namen der Funktion fest, mit der Sie Autorisierungscodes an Ihre Plattform senden.

Wichtig :Für das beste Gleichgewicht zwischen Nutzerfreundlichkeit und Sicherheit wird die Verwendung des UX-Flows im Pop-up-Modus mit dem Autorisierungscode-Modell empfohlen.

Schutz vor CSRF-Angriffen

Um CSRF-Angriffe (Cross-Site-Request-Forgery) zu verhindern, werden für die UX-Abläufe im Weiterleitungs- und Pop-up-Modus leicht unterschiedliche Techniken verwendet. Für den Weiterleitungsmodus wird der OAuth 2.0-Parameter state verwendet. Weitere Informationen zum Generieren und Validieren des Parameters state finden Sie unter RFC6749 Abschnitt 10.12 „Cross-Site Request Forgery“. Im Pop-up-Modus fügen Sie Ihren Anfragen einen benutzerdefinierten HTTP-Header hinzu und prüfen dann auf Ihrem Server, ob er mit dem erwarteten Wert und Ursprung übereinstimmt.

Wählen Sie einen UX-Modus aus, um ein Code-Snippet mit Authentifizierungscode und CSRF-Verarbeitung aufzurufen:

Weiterleitungsmodus

Initialisiere einen Client, bei dem Google den Browser des Nutzers an deinen Authentifizierungsendpunkt weiterleitet und den Authentifizierungscode als URL-Parameter übergibt.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: "https://your.domain/code_callback_endpoint",
  state: "YOUR_BINDING_VALUE"
});

Pop-up-Modus

Initiieren Sie einen Client, bei dem der Browser des Nutzers einen Autorisierungscode von Google empfängt und an Ihren Server sendet.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', code_receiver_uri, true);
    xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    // Set custom header for CRSF
    xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
    xhr.onload = function() {
      console.log('Auth code response: ' + xhr.responseText);
    };
    xhr.send('code=' + response.code);
  },
});

OAuth 2.0-Codeablauf auslösen

Rufen Sie die Methode requestCode() des Codeclients auf, um den User Flow auszulösen:

<button onclick="client.requestCode();">Authorize with Google</button>

Dazu muss sich der Nutzer in einem Google-Konto anmelden und der Freigabe einzelner Zugriffsbereiche zustimmen, bevor ein Autorisierungscode entweder an Ihren Weiterleitungsendpunkt oder an Ihren Rückruf-Handler zurückgegeben wird.

Umgang mit Authentifizierungscodes

Google generiert einen eindeutigen Autorisierungscode pro Nutzer, den du auf deinem Back-End-Server empfängst und überprüfst.

Im Pop-up-Modus leitet der von callback angegebene Handler, der im Browser des Nutzers ausgeführt wird, den Autorisierungscode an einen von deiner Plattform gehosteten Endpunkt weiter.

Im Weiterleitungsmodus wird eine GET-Anfrage an den durch redirect_url angegebenen Endpunkt gesendet. Der Autorisierungscode wird dabei im URL-Parameter code angegeben. So erhalten Sie den Autorisierungscode:

• Erstellen Sie einen neuen Autorisierungsendpunkt, wenn Sie noch keine Implementierung haben, oder

• Aktualisieren Sie den vorhandenen Endpunkt, damit GET-Anfragen und URL-Parameter akzeptiert werden. Bisher wurde eine PUT-Anfrage mit dem Autorisierungscodewert in der Nutzlast verwendet.

Autorisierungsendpunkt

Dein Autorisierungscode-Endpunkt muss GET-Anfragen mit den folgenden URL-Suchstring-Parametern verarbeiten:

Name	Wert
authuser	Authentifizierung für die Nutzeranmeldung anfordern
Code	Ein von Google generierter OAuth2-Autorisierungscode
HD	Die gehostete Domain des Nutzerkontos
prompt	Dialog zur Einholung der Nutzereinwilligung
Bereich	Durch Leerzeichen getrennte Liste mit einem oder mehreren OAuth2-Bereichen, die autorisiert werden sollen
Bundesstaat	CRSF-Statusvariable

Beispiel für eine GET-Anfrage mit URL-Parametern an einen Endpunkt namens auth-code, der von beispiel.de gehostet wird:

Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent

Wenn der Ablauf mit Autorisierungscode durch ältere JavaScript-Bibliotheken oder durch direkte Aufrufe von Google OAuth 2.0-Endpunkten initiiert wird, wird eine POST-Anfrage verwendet.

Beispiel für eine POST-Anfrage, die den Autorisierungscode als Nutzlast im HTTP-Anfragetext enthält:

Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw

Wichtig :Bisher wurde POST für Anfragen verwendet. Aktualisieren Sie Ihren Handler, damit er sowohl GET- als auch POST-Anfragen akzeptiert. Sie können auch zwei unterschiedliche Endpunkte hosten, wenn Sie weiterhin ältere JS-Bibliotheken verwenden oder Google OAuth 2.0-Endpunkte direkt aufrufen möchten, während Sie die Google Identity Services-Bibliothek verwenden.

Die Anfrage validieren

Führen Sie auf Ihrem Server die folgenden Schritte aus, um CSRF-Angriffe zu vermeiden.

Prüfen Sie den Wert des Parameters state für den Weiterleitungsmodus.

Prüfen Sie, ob der X-Requested-With: XmlHttpRequest-Header für den Pop-up-Modus festgelegt ist.

Sie sollten erst dann Aktualisierungs- und Zugriffstokens von Google abrufen, wenn Sie die Autorisierungscodeanfrage erfolgreich bestätigt haben.

Zugriffs- und Aktualisierungstokens abrufen

Nachdem Ihre Back-End-Plattform einen Autorisierungscode von Google erhalten und die Anfrage bestätigt hat, können Sie mit dem Autorisierungscode Zugriffs- und Aktualisierungstokens von Google abrufen, um API-Aufrufe auszuführen.

Folgen Sie der Anleitung ab Schritt 5: Autorisierungscode gegen Aktualisierungs- und Zugriffstokens austauschen im Leitfaden OAuth 2.0 für Webserveranwendungen verwenden.

Tokens verwalten

Ihre Plattform speichert Aktualisierungstokens sicher. Lösche gespeicherte Aktualisierungstokens, wenn Nutzerkonten entfernt werden oder die Nutzereinwilligung über google.accounts.oauth2.revoke oder direkt unter https://myaccount.google.com/permissions widerrufen wird.

Optional können Sie RISC verwenden, um Nutzerkonten mit dem geräteübergreifenden Schutz zu schützen.

Normalerweise ruft Ihre Backend-Plattform Google APIs mit einem Zugriffstoken auf. Wenn Ihre Webanwendung Google APIs auch direkt über den Browser des Nutzers aufruft, müssen Sie eine Möglichkeit implementieren, das Zugriffstoken für Ihre Webanwendung freizugeben. Dies ist nicht Gegenstand dieses Leitfadens. Wenn Sie diesen Ansatz verfolgen und die Google API-Clientbibliothek für JavaScript verwenden, speichern Sie das Zugriffstoken vorübergehend mit gapi.client.SetToken() im Browserspeicher und ermöglichen Sie der Bibliothek, Google APIs aufzurufen.