Codemodell verwenden

Mit der Google Identity Services-Bibliothek können Nutzer einen Autorisierungscode von Google anfordern. Dazu können sie entweder ein browserbasiertes Popup oder einen Redirect-UX-Ablauf verwenden. Dadurch wird ein sicherer OAuth 2.0-Ablauf gestartet und ein Zugriffstoken generiert, mit dem Google-APIs im Namen eines Nutzers aufgerufen werden können.

Zusammenfassung des OAuth 2.0-Vorgangs mit Autorisierungscode:

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

Vorbereitung

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

Code-Client initialisieren

Mit der Methode google.accounts.oauth2.initCodeClient() wird ein Code-Client initialisiert.

Pop-up- oder Weiterleitungsmodus

Sie können einen Autorisierungscode entweder über den Nutzerfluss im Modus Weiterleitung oder Pop-up freigeben. Im Weiterleitungsmodus hosten Sie einen OAuth2-Autorisierungsendpunkt auf Ihrem Server und Google leitet den User-Agent zu diesem Endpunkt weiter. Der Autorisierungscode wird als URL-Parameter übergeben. Im Pop-up-Modus definieren Sie einen JavaScript-Callback-Handler, der den Autorisierungscode an Ihren Server sendet. Der Pop-up-Modus kann verwendet werden, um eine nahtlose Nutzererfahrung zu bieten, ohne dass Besucher Ihre Website verlassen müssen.

So initialisieren Sie einen Client für die:

• Leiten Sie den UX-Ablauf um, legen Sie ux_mode auf redirect fest und den Wert von redirect_uri auf den Autorisierungscode-Endpunkt Ihrer Plattform. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in der Google Cloud Console konfiguriert haben. Außerdem muss er den Validierungsregeln für Weiterleitungs-URIs entsprechen.

• Popup-UX-Ablauf: Setzen Sie ux_mode auf popup und den Wert von callback auf den Namen der Funktion, mit der Sie Autorisierungscodes an Ihre Plattform senden. Der Wert von redirect_uri ist standardmäßig der Ursprung der Seite, die initCodeClient aufruft. Dieser Wert wird später im Ablauf verwendet, wenn der Autorisierungscode gegen ein Zugriffs- oder Aktualisierungstoken eingetauscht wird. Wenn beispielsweise https://www.example.com/index.html initCodeClient aufruft, ist der Ursprung https://www.example.com der Wert von redirect_url.

Schutz vor CSRF-Angriffen

Um CSRF-Angriffe (Cross-Site Request Forgery) zu verhindern, werden für die UX-Abläufe im Redirect- und Popup-Modus leicht unterschiedliche Techniken eingesetzt. Im Weiterleitungsmodus wird der OAuth 2.0-Parameter state verwendet. Weitere Informationen zum Generieren und Validieren des state-Parameters finden Sie in RFC6749, Abschnitt 10.12, Cross-Site Request Forgery. Im Pop-up-Modus fügen Sie Ihren Anfragen einen benutzerdefinierten HTTP-Header hinzu und bestätigen dann auf Ihrem Server, dass er dem erwarteten Wert und Ursprung entspricht.

Wählen Sie einen UX-Modus aus, um ein Code-Snippet mit der Verarbeitung von Autorisierungscode und CSRF anzuzeigen:

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", 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-Vorgang mit Autorisierungscode auslösen

Rufen Sie die Methode requestCode() des Code-Clients 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 Bereiche zustimmen, bevor ein Autorisierungscode an Ihren Weiterleitungs-Endpunkt oder Ihren Callback-Handler zurückgegeben wird.

Umgang mit Autorisierungscodes

Google generiert einen eindeutigen Autorisierungscode pro Nutzer, den Sie auf Ihrem Backend-Server empfangen und bestätigen.

Im Pop-up-Modus leitet der Handler, der durch callback angegeben wird und im Browser des Nutzers ausgeführt wird, den Autorisierungscode an einen Endpunkt weiter, der von Ihrer Plattform gehostet wird.

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

• Erstellen Sie einen neuen Autorisierungs-Endpunkt, wenn Sie noch keine Implementierung haben, oder

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

Autorisierungsendpunkt

Ihr Autorisierungscode-Endpunkt muss GET-Anfragen mit den folgenden URL-Suchstringparametern verarbeiten:

Beispiel für eine GET-Anfrage mit URL-Parametern an einen Endpunkt mit dem Namen auth-code, der von example.com 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 Autorisierungscode-Vorgang von älteren 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

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.

Bestätigen Sie, dass der X-Requested-With: XmlHttpRequest-Header für den Pop-up-Modus festgelegt ist.

Sie sollten dann erst Aktualisierungs- und Zugriffstokens von Google abrufen, wenn Sie die Anfrage für den Autorisierungscode erfolgreich bestätigt haben.

Zugriffs- und Aktualisierungstokens abrufen

Nachdem Ihre Backend-Plattform einen Autorisierungscode von Google erhalten und die Anfrage bestätigt hat, verwenden Sie den Autorisierungscode, um Zugriffs- und Aktualisierungstokens von Google abzurufen und API-Aufrufe zu starten.

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

Tokens verwalten

Ihre Plattform speichert Aktualisierungstokens sicher. Löschen Sie gespeicherte Aktualisierungstokens, wenn Nutzerkonten entfernt werden oder die Einwilligung des Nutzers von google.accounts.oauth2.revoke oder direkt über https://myaccount.google.com/permissions widerrufen wird.

Optional können Sie RISC verwenden, um Nutzerkonten mit Cross-Account Protection zu schützen.

Normalerweise ruft Ihre Backend-Plattform Google APIs mit einem Zugriffstoken auf. Wenn Ihre Web-App auch direkt Google-APIs über den Browser des Nutzers aufruft, müssen Sie eine Möglichkeit implementieren, das Zugriffstoken für Ihre Webanwendung freizugeben. Dies wird in diesem Leitfaden nicht behandelt. Wenn Sie diesen Ansatz verfolgen und die Google API-Clientbibliothek für JavaScript verwenden, können Sie gapi.client.SetToken() nutzen, um das Zugriffstoken vorübergehend im Browserspeicher zu speichern und der Bibliothek zu ermöglichen, Google APIs aufzurufen.