Von Google Log-in migrieren

In dieser Anleitung erfahren Sie, welche Änderungen erforderlich sind und welche Schritte Sie ausführen müssen, um JavaScript-Bibliotheken für die Authentifizierung von der älteren Google Sign-In-Plattformbibliothek zur neueren Google Identity Services-Bibliothek zu migrieren.

Wenn Ihr Client die Google API-Clientbibliothek für JavaScript oder andere frühere Bibliotheken für die Autorisierung verwendet, finden Sie unter Zu Google Identity Services migrieren weitere Informationen.

Authentifizierung und Autorisierung

Bei der Authentifizierung wird festgestellt, wer jemand ist. Sie wird häufig als Nutzerregistrierung oder Anmeldung bezeichnet. Die Autorisierung ist der Vorgang, bei dem der Zugriff auf Daten oder Ressourcen gewährt oder abgelehnt wird. Ihre App fordert beispielsweise die Zustimmung des Nutzers zum Zugriff auf sein Google Drive an.

Wie die frühere Bibliothek der Google Log-in-Plattform unterstützt auch die neue Bibliothek der Google Identity Services sowohl Authentifizierungs- als auch Autorisierungsverfahren.

In der neueren Bibliothek werden die beiden Prozesse jedoch getrennt, um die Integration von Google-Konten in Ihre Anwendung für Entwickler zu vereinfachen.

Wenn Ihr Anwendungsfall nur die Authentifizierung betrifft, lesen Sie diese Seite.

Wenn Ihr Anwendungsfall eine Autorisierung umfasst, lesen Sie die Artikel Funktionsweise der Nutzerautorisierung und Zu Google Identity Services migrieren, um sicherzustellen, dass Ihre Anwendung die neuen und verbesserten APIs verwendet.

Änderungen

Für Nutzer bietet die neue Google Identity Services-Bibliothek zahlreiche Verbesserungen der Nutzerfreundlichkeit. Zu den Highlights gehören:

• Neue, reibungslose One Tap- und automatische Anmeldungsabläufe mit weniger einzelnen Schritten,
• eine überarbeitete Anmeldeschaltfläche mit Nutzerpersonalisierung,
• Ein einheitliches Branding und ein einheitliches Anmeldeverhalten im Web verbessern das Verständnis und das Vertrauen.
• schnell zu den Inhalten gelangen. Nutzer können sich von überall auf Ihrer Website direkt registrieren und anmelden, ohne zuerst eine Anmelde- oder Kontoseite aufrufen zu müssen.

Für Entwickler haben wir uns darauf konzentriert, die Komplexität zu reduzieren, die Sicherheit zu verbessern und die Integration so schnell wie möglich zu gestalten. Zu diesen Verbesserungen gehören:

• Die Möglichkeit, die Nutzeranmeldung in den statischen Inhalten Ihrer Website nur mithilfe von HTML hinzuzufügen,
• die Authentifizierung bei der Anmeldung von der Autorisierung und der Freigabe von Nutzerdaten getrennt ist, ist die komplexe OAuth 2.0-Integration nicht mehr erforderlich, um Nutzer auf Ihrer Website anzumelden.
• Sowohl der Pop-up- als auch der Weiterleitungsmodus werden weiterhin unterstützt, aber die OAuth 2.0-Infrastruktur von Google leitet jetzt zum Anmeldeendpunkt deines Back-End-Servers weiter.
• Zusammenführung der Funktionen der beiden früheren JavaScript-Bibliotheken für Google Identity und Google API in einer einzigen neuen Bibliothek,
• Bei Anmeldeantworten können Sie jetzt entscheiden, ob Sie ein Promise verwenden möchten oder nicht. Die Indirektion über Getter-Stilfunktionen wurde der Einfachheit halber entfernt.

Beispiel für die Migration von Anmeldedaten

Wenn du von der vorhandenen Google Log-in-Schaltfläche migrierst und nur Nutzer auf deiner Website anmelden möchtest, ist die einfachste Änderung ein Upgrade auf die neue personalisierte Schaltfläche. Dazu können Sie die JavaScript-Bibliotheken austauschen und Ihre Codebasis so aktualisieren, dass ein neues Anmeldeobjekt verwendet wird.

Bibliotheken und Konfiguration

Die frühere Google Sign-in-Plattformbibliothek: apis.google.com/js/platform.js und die Google APIs-Clientbibliothek für JavaScript: gapi.client sind für die Nutzerauthentifizierung und -autorisierung nicht mehr erforderlich. Sie wurden durch eine einzige neue JavaScript-Bibliothek von Google Identity Services ersetzt: accounts.google.com/gsi/client.

Die drei zuvor genannten JavaScript-Module api, client und platform, die für die Anmeldung verwendet werden, werden alle von apis.google.com geladen. Hier sind einige typische Stellen, an denen die ältere Bibliothek auf Ihrer Website enthalten sein könnte:

• lädt die Standard-Anmeldeschaltfläche apis.google.com/js/platform.js,
• eine benutzerdefinierte Schaltflächengrafik lädt apis.google.com/js/api:client.js und
• Die direkte Verwendung von gapi.client lädt apis.google.com/js/api.js.

In den meisten Fällen können Sie Ihre vorhandenen Anmeldedaten für die Client-ID der Webanwendung weiterhin verwenden. Im Rahmen der Migration empfehlen wir Ihnen, unsere OAuth 2.0-Richtlinien zu lesen und in der Google API Console die folgenden Clienteinstellungen zu prüfen und gegebenenfalls zu aktualisieren:

• Ihre Test- und Produktions-Apps separate Projekte und eigene Client-IDs haben.
• der Typ der OAuth 2.0-Client-ID „Webanwendung“ ist und
• HTTPS wird für autorisierte JavaScript-Quellen und Weiterleitungs-URIs verwendet.

Betroffenen Code ermitteln und testen

Mit einem Debug-Cookie können Sie den betroffenen Code finden und das Verhalten nach der Einstellung testen.

In großen oder komplexen Anwendungen kann es schwierig sein, den gesamten Code zu finden, der von der Einstellung des Moduls gapi.auth2 betroffen ist. Wenn Sie die bestehende Nutzung bald eingestellter Funktionen in der Console protokollieren möchten, legen Sie den Wert des G_AUTH2_MIGRATION-Cookies auf informational fest. Optional können Sie einen Doppelpunkt gefolgt von einem Schlüsselwert hinzufügen, um auch im Sitzungsspeicher zu protokollieren. Nach der Anmeldung und dem Erhalt der Anmeldedaten werden die erfassten Protokolle zur späteren Analyse an ein Backend gesendet. Beispiel: informational:showauth2use speichert den Ursprung und die URL in einem Sitzungsspeicherschlüssel namens showauth2use.

Wenn Sie das App-Verhalten prüfen möchten, wenn das gapi.auth2-Modul nicht mehr geladen wird, legen Sie den Wert des G_AUTH2_MIGRATION-Cookies auf enforced fest. So können Sie das Verhalten nach der Einstellung vor dem Datum der Erzwingung testen.

Mögliche G_AUTH2_MIGRATION-Cookie-Werte:

• enforced Modul gapi.auth2 wird nicht geladen.
• informational Verwendung eingestellter Funktionen in der JS-Konsole protokollieren. Wenn ein optionaler Schlüsselname festgelegt ist, wird auch im Sitzungsspeicher protokolliert: informational:key-name.

Um die Auswirkungen auf die Nutzer zu minimieren, wird empfohlen, dieses Cookie zuerst lokal während der Entwicklung und beim Testen lokal zu speichern, bevor Sie es in Produktionsumgebungen verwenden.

HTML und JavaScript

In diesem Szenario für die Anmeldung nur zur Authentifizierung werden Beispielcode und Renderings der vorhandenen Schaltfläche „Über Google anmelden“ angezeigt. Wählen Sie entweder den Pop-up- oder den Weiterleitungsmodus aus, um die Unterschiede bei der Verarbeitung der Authentifizierungsantwort zu sehen, die entweder über einen JavaScript-Callback oder eine sichere Weiterleitung zum Anmelde-Endpunkt Ihres Backend-Servers erfolgt.

Je früher

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

Die neue Art

Wenn Sie die neue Bibliothek in einem Szenario für die Anmeldung nur zur Authentifizierung verwenden möchten, wählen Sie entweder den Pop-up- oder den Weiterleitungsmodus aus und ersetzen Sie die vorhandene Implementierung auf Ihrer Anmeldeseite durch das Codebeispiel.

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

In diesem Beispiel, das sich nur auf die Authentifizierung bezieht, ersetzen die neue accounts.google.com/gsi/client-Bibliothek, die g_id_signin-Klasse und das g_id_onload-Objekt die vorherige apis.google.com/js/platform.js-Bibliothek und das g-signin2-Objekt.

Im Beispielcode wird nicht nur die neue personalisierte Schaltfläche gerendert, sondern auch das neue One Tap-Pop-up angezeigt. Wir empfehlen Ihnen, überall dort, wo Sie die personalisierte Schaltfläche anzeigen, auch das Pop-up für die Anmeldung mit nur einem Tippen zu präsentieren, um die Abläufe bei der Registrierung und Anmeldung zu vereinfachen.

Die neue personalisierte Schaltfläche kann auch allein angezeigt werden, ohne dass gleichzeitig das One Tap-Dialogfeld angezeigt wird. Aufgrund der erhöhten Anmeldehürden wird dies jedoch nicht empfohlen. Setzen Sie dazu das Attribut data-auto_prompt auf false.

HTML- und JavaScript-APIs

Im vorherigen Beispiel wird gezeigt, wie Sie mit der neuen HTML API eine Anmeldung auf Ihrer Website hinzufügen. Alternativ können Sie die funktional gleichwertige JavaScript API verwenden oder HTML- und JavaScript APIs auf Ihrer Website kombinieren.

Im Codegenerator können Sie sich interaktiv Optionen zur Schaltflächenanpassung ansehen, z. B. den Rückruftyp und Attribute wie Farbe, Größe, Form, Text und Design. Damit können Sie schnell verschiedene Optionen vergleichen und HTML-Snippets für Ihre Website generieren.

Über One Tap auf jeder Seite anmelden

One Tap ist eine neue, einfache Möglichkeit für Nutzer, sich auf Ihrer Website zu registrieren oder anzumelden. Sie können die Nutzeranmeldung direkt auf jeder Seite Ihrer Website aktivieren und Nutzer müssen nicht mehr eine spezielle Anmeldeseite aufrufen. Anders ausgedrückt: Dadurch wird der Anmelde- und Anmeldevorgang vereinfacht, da Nutzer sich auf anderen Seiten als Ihrer Anmeldeseite flexibel registrieren und anmelden können.

Wenn Sie die Anmeldung von jeder Seite aus ermöglichen möchten, sollten Sie g_id_onload in einer gemeinsamen Kopf- oder Fußzeile oder einem anderen Objekt auf Ihrer gesamten Website einfügen.

Wir empfehlen außerdem, g_id_signin hinzuzufügen, über das die personalisierte Anmeldeschaltfläche nur auf den Anmelde- oder Nutzerkontoverwaltungsseiten angezeigt wird. Geben Sie Nutzern Wahlmöglichkeiten für die Registrierung oder Anmeldung, indem Sie die Schaltfläche neben anderen Schaltflächen für föderierte Identitätsanbieter sowie Eingabefeldern für Nutzername und Passwort anzeigen.

Tokenantwort

Für die Nutzeranmeldung müssen Sie keine OAuth 2.0-Autorisierungscodes, Zugriffstokens oder Aktualisierungstokens mehr kennen oder verwenden. Stattdessen wird ein JWT-ID-Token (JSON Web Token) verwendet, um den Anmeldestatus und das Nutzerprofil freizugeben. Außerdem müssen Sie zum Arbeiten mit Nutzerprofildaten nicht mehr die Zugriffsmethoden im „Getter“-Stil verwenden.

Sichere, von Google signierte JWT-ID-Token-Anmeldedaten werden entweder

• an den browserbasierten JavaScript-Callback-Handler des Nutzers im Pop-up-Modus oder
• zu Ihrem Backend-Server über eine Google-Weiterleitung zu Ihrem Anmeldeendpunkt, wenn die Schaltfläche „Über Google anmelden“ ux_mode auf redirect festgelegt ist.

Aktualisieren Sie in beiden Fällen Ihre vorhandenen Callback-Handler, indem Sie Folgendes entfernen:

• Anrufe an googleUser.getBasicProfile(),
• Verweise auf BasicProfile und zugehörige Aufrufe der Methoden getId(), getName(), getGivenName(), getFamilyName(), getImageUrl() und getEmail()
• Verwendung des Objekts AuthResponse

Verwende stattdessen direkte Verweise auf credential-Unterfelder im neuen JWT-Objekt CredentialResponse, um mit Nutzerprofildaten zu arbeiten.

Außerdem müssen Sie, und zwar nur im Weiterleitungsmodus, CSRF-Angriffe (Cross-Site Request Forgery) verhindern und das Google-ID-Token auf Ihrem Backend-Server bestätigen.

Um besser zu verstehen, wie Nutzer mit Ihrer Website interagieren, können Sie mit dem Feld select_by in der CredentialResponse das Ergebnis der Nutzereinwilligung und den verwendeten Anmeldevorgang ermitteln.

Nutzereinwilligung und Widerruf der Berechtigung

Wenn sich ein Nutzer zum ersten Mal auf Ihrer Website anmeldet, wird er von Google aufgefordert, seine Einwilligung zur Freigabe seines Kontoprofils für Ihre App zu erteilen. Erst nach der Einwilligung wird das Profil des Nutzers in einer Credential-Nutzlast eines ID-Tokens an Ihre App gesendet. Das Entziehen des Zugriffs auf dieses Profil entspricht dem Entziehen eines Zugriffstokens in der früheren Anmeldebibliothek.

Nutzer können Berechtigungen widerrufen und die Verknüpfung Ihrer App mit ihrem Google-Konto unter https://myaccount.google.com/permissions aufheben. Alternativ können sie die Verbindung zu Ihrer App direkt trennen, indem sie einen von Ihnen implementierten API-Aufruf auslösen. Die frühere Methode disconnect wurde durch die neuere Methode revoke ersetzt.

Wenn ein Nutzer sein Konto auf deiner Plattform löscht, sollte revoke verwendet werden, um die Verknüpfung deiner App mit seinem Google-Konto aufzuheben.

Bisher konnte auth2.signOut() verwendet werden, um die Abmeldung von Nutzern aus Ihrer App zu verwalten. Jegliche Verwendung von auth2.signOut() sollte entfernt werden. Stattdessen sollte Ihre App den Sitzungsstatus und den Anmeldestatus pro Nutzer direkt verwalten.

Sitzungsstatus und Listener

Die neue Bibliothek speichert weder den Anmeldestatus noch den Sitzungsstatus für Ihre Webanwendung.

Der Anmeldestatus eines Google-Kontos und der Sitzungsstatus und Anmeldestatus Ihrer App sind unterschiedliche Konzepte.

Der Anmeldestatus des Nutzers in seinem Google-Konto und in Ihrer App sind voneinander unabhängig, mit Ausnahme des Anmeldevorgangs selbst, wenn Sie wissen, dass der Nutzer erfolgreich authentifiziert wurde und in seinem Google-Konto angemeldet ist.

Wenn „Über Google anmelden“, „One Tap“ oder die automatische Anmeldung auf Ihrer Website verfügbar sind, müssen sich Nutzer zuerst in ihrem Google-Konto anmelden, um Folgendes zu tun:

• bei der Erstregistrierung oder Anmeldung auf Ihrer Website ihre Einwilligung zur Weitergabe ihres Nutzerprofils geben,
• und später für die Anmeldung bei weiteren Besuchen Ihrer Website.

Nutzer können sich anmelden, abmelden oder zu einem anderen Google-Konto wechseln, während auf Ihrer Website eine aktive Sitzung mit Anmeldung besteht.

Sie sind jetzt dafür verantwortlich, den Anmeldestatus der Nutzer Ihrer Webanwendung direkt zu verwalten. Bisher konnte mit Google Log-in der Sitzungsstatus des Nutzers überwacht werden.

Entfernen Sie alle Verweise auf auth2.attachClickHandler() und die zugehörigen registrierten Callback-Handler.

Bisher wurden Listener verwendet, um Änderungen am Anmeldestatus des Google-Kontos eines Nutzers zu teilen. Listener werden nicht mehr unterstützt.

Entfernen Sie alle Verweise auf listen(), auth2.currentUser und auth2.isSignedIn.

Kekse

„Über Google anmelden“ verwendet Cookies in begrenztem Umfang. Es folgt eine Beschreibung dieser Cookies. Weitere Informationen zu den anderen von Google verwendeten Cookie-Arten finden Sie unter So verwendet Google Cookies.

Das G_ENABLED_IDPS-Cookie, das von der vorherigen Google Log-in Platform Library gesetzt wurde, wird nicht mehr verwendet.

Die neue Bibliothek für Google Identity Services kann je nach Ihren Konfigurationsoptionen optional diese domainübergreifenden Cookies setzen:

• g_state speichert den Abmeldestatus des Nutzers und wird bei Verwendung des One Tap-Pop-ups oder der automatischen Anmeldung festgelegt.

• g_csrf_token ist ein Double-submit-Cookie, das verwendet wird, um CSRF-Angriffe zu verhindern, und wird gesetzt, wenn Ihr Anmeldeendpunkt aufgerufen wird. Der Wert für Ihren Anmelde-URI kann explizit festgelegt werden oder standardmäßig auf den URI der aktuellen Seite festgelegt werden. Dein Anmeldeendpunkt kann unter den folgenden Bedingungen aufgerufen werden, wenn du

  • HTML API mit data-ux_mode=redirect oder wenn data-login_uri festgelegt ist oder

  • JavaScript API mit ux_mode=redirect und google.accounts.id.prompt() wird nicht für die Anzeige von One Tap oder der automatischen Anmeldung verwendet.

Wenn Sie einen Dienst zur Verwaltung von Cookies haben, fügen Sie die beiden neuen Cookies hinzu und entfernen Sie das vorherige Cookie, sobald die Migration abgeschlossen ist.

Wenn du mehrere Domains oder Subdomains verwaltest, findest du unter One Tap auf Subdomains weitere Informationen zur Verwendung des g_state-Cookies.

Referenz zur Objektmigration für die Nutzeranmeldung