Google Log-in mit FedCM APIs

In diesem Leitfaden wird die Verwendung von FedCM APIs durch die Google Sign-in-Plattformbibliothek beschrieben. Zu den Themen gehören die Zeitleiste und die Nächsten Schritte für ein abwärtskompatibles Update der Bibliothek, wie Sie eine Auswirkungsanalyse durchführen und prüfen, ob die Nutzeranmeldung weiterhin wie erwartet funktioniert, sowie bei Bedarf eine Anleitung zum Aktualisieren Ihrer Webanwendung. Außerdem werden Optionen zum Verwalten der Übergangsphase und zum Holen von Hilfe behandelt.

Status der Bibliothek

Neue Webanwendungen können die eingestellte Plattformbibliothek für die Google Sign-in-Plattform nicht mehr verwenden. Apps, die die Bibliothek bereits nutzen, können dies bis auf Weiteres tun. Ein endgültiges Enddatum für die Einstellung der Bibliothek wurde noch nicht festgelegt. Weitere Informationen finden Sie unter Einstellung des Supports und Einstellung der Dienste.

Durch ein abwärtskompatibles Update werden der Google Sign-In-Bibliothek FedCM APIs hinzugefügt. Die meisten Änderungen sind nahtlos. Durch das Update gibt es jedoch Unterschiede bei Aufforderungen an Nutzer, der Permissions Policy für iframes und der Content Security Policy (CSP). Diese Änderungen können sich auf Ihre Webanwendung auswirken und Änderungen am Anwendungscode und an der Websitekonfiguration erfordern.

Während der Übergangsphase wird mit einer Konfigurationsoption festgelegt, ob FedCM APIs bei der Nutzeranmeldung verwendet werden.

Nach der Übergangsphase sind FedCM APIs für alle Web-Apps, die die Google Sign-In-Bibliothek verwenden, obligatorisch.

Zeitachse

Letzte Aktualisierung: September 2024

Hier sind die Termine und Änderungen, die sich auf das Anmeldeverhalten von Nutzern auswirken:

  • März 2023: Einstellung der Unterstützung für die Google Sign-in-Plattformbibliothek.
  • Die Übergangsphase im Juli 2024 beginnt und die Google Sign-in-Plattformbibliothek wird um die Unterstützung für FedCM APIs erweitert. Standardmäßig steuert Google während dieser Zeit den Prozentsatz der Nutzeranmeldungen, die über FedCM erfolgen. Web-Apps können dieses Verhalten mit dem Parameter use_fedcm explizit überschreiben.
  • März 2025: Erforderliche Einführung von FedCM APIs in der Google Log-in-Plattformbibliothek. Danach wird der Parameter use_fedcm ignoriert und alle Anfragen zur Nutzeranmeldung nutzen FedCM.

Nächste Schritte

Sie haben drei Möglichkeiten:

  1. Führen Sie eine Folgenabschätzung durch und aktualisieren Sie Ihre Webanwendung bei Bedarf. Bei diesem Ansatz wird geprüft, ob Funktionen verwendet werden, die Änderungen an Ihrer Webanwendung erfordern. Eine Anleitung dazu finden Sie im nächsten Abschnitt dieses Leitfadens.
  2. Wechseln Sie zur Google Identity Services-Bibliothek (GIS). Wir empfehlen dringend, auf die neueste und unterstützte Anmeldebibliothek umzustellen. Folgen Sie dazu dieser Anleitung.
  3. Nichts unternehmen: Ihre Webanwendung wird automatisch aktualisiert, wenn die Google Sign-in-Bibliothek auf FedCM APIs für die Nutzeranmeldung umgestellt wird. Das ist der geringste Aufwand, aber es besteht das Risiko, dass sich Nutzer nicht in Ihrer Webanwendung anmelden können.

Folgenabschätzung durchführen

Anhand dieser Anleitung können Sie feststellen, ob Ihre Webanwendung durch ein abwärtskompatibles Update nahtlos aktualisiert werden kann oder ob Änderungen erforderlich sind, damit sich Nutzer anmelden können, wenn die FedCM APIs vollständig in die Google Sign-in-Plattformbibliothek übernommen werden.

Einrichtung

Browser-APIs und die neueste Version der Plattformbibliothek von Google Log-in sind erforderlich, um FedCM bei der Nutzeranmeldung zu verwenden.

Bevor Sie fortfahren, sollten Sie Folgendes beachten:

  • Aktualisieren Sie Chrome auf die neueste Version. Chrome für Android benötigt die Version M128 oder höher und kann nicht mit früheren Versionen getestet werden.
  • Legen Sie use_fedcm auf true fest, wenn Sie die Google Sign-in-Plattformbibliothek in Ihrer Webanwendung initialisieren. Normalerweise sieht die Initialisierung so aus:
    • gapi.client.init({use_fedcm: true}) oder
    • gapi.auth2.init({use_fedcm: true}) oder
    • gapi.auth2.authorize({use_fedcm: true}).
  • Entwerten Sie die im Cache gespeicherten Versionen der Google Sign-in-Plattformbibliothek. Normalerweise ist dieser Schritt nicht erforderlich, da die neueste Version der Bibliothek direkt in den Browser heruntergeladen wird, indem api.js, client.js oder platform.js in ein <script src>-Tag eingefügt wird. In der Anfrage kann einer dieser Bundle-Namen für die Bibliothek verwendet werden.

  • Bestätigen Sie die OAuth-Einstellungen für Ihre OAuth-Client-ID:

    1. Öffnen Sie die Seite „Anmeldedaten“ der

    2. Prüfen Sie, ob die URI Ihrer Website in Autorisierte JavaScript-Quellen enthalten ist. Der URI enthält nur das Schema und den voll qualifizierten Hostnamen. Beispiel: https://www.example.com.

    3. Optional können Anmeldedaten auch über eine Weiterleitung an einen von Ihnen gehosteten Endpunkt statt über einen JavaScript-Callback zurückgegeben werden. Prüfen Sie in diesem Fall, ob Ihre Weiterleitungs-URIs in Autorisierte Weiterleitungs-URIs enthalten sind. Weiterleitungs-URIs enthalten das Schema, den voll qualifizierten Hostnamen und den Pfad und müssen den Gültigkeitsregeln für Weiterleitungs-URIs entsprechen. Beispiel: https://www.example.com/auth-receiver.

Test

Nachdem Sie der Anleitung zur Einrichtung gefolgt sind:

Anfrage an die Google Sign-in-Bibliothek aufrufen

Prüfen Sie, ob Änderungen an der permissions-policy und der Content Security Policy erforderlich sind. Sehen Sie sich dazu die Anfrage für die Google Sign-in-Plattformbibliothek an. Suchen Sie dazu die Anfrage anhand des Namens und des Ursprungs der Bibliothek:

  • Öffnen Sie in Chrome den Bereich Netzwerk in den Entwicklertools und aktualisieren Sie die Seite.
  • Verwenden Sie die Werte in den Spalten Domain und Name, um die Bibliotheksanfrage zu finden:
    • Domain ist apis.google.com und
    • Der Name ist entweder api.js, client.js oder platform.js. Der genaue Wert von „Name“ hängt vom vom Dokument angeforderten Bibliothekspaket ab.

Filtern Sie beispielsweise nach apis.google.com in der Spalte Domain und nach platform.js in der Spalte Name.

iFrame-Berechtigungsrichtlinie prüfen

Auf Ihrer Website wird möglicherweise die Google Log-in-Plattformbibliothek in einem plattformübergreifenden IFrame verwendet. In diesem Fall ist ein Update erforderlich.

Nachdem Sie der Anleitung zum Suchen der Google Sign-in-Bibliotheksanfrage gefolgt sind, wählen Sie die Google Sign-in-Bibliotheksanfrage im DevTools-Bereich Netzwerk aus und suchen Sie auf dem Tab Header im Bereich Anfrageheader nach dem Header Sec-Fetch-Site. Wenn der Wert des Headers:

  • same-site oder same-origin, gelten keine richtlinien für unterschiedliche Ursprünge und es sind keine Änderungen erforderlich.
  • cross-origin Änderungen können erforderlich sein, wenn ein Iframe verwendet wird.

So prüfen Sie, ob ein Iframe vorhanden ist:

  • Wählen Sie in den Chrome-Entwicklertools den Bereich Elemente aus.
  • Mit Strg + F können Sie im Dokument nach einem Iframe suchen.

Wenn ein Iframe gefunden wird, prüfen Sie das Dokument auf Aufrufe von gapi.auth2-Funktionen oder script src-Direktiven, die die Google Sign-in-Bibliothek im Iframe laden. Trifft das auf Sie zu, haben Sie folgende Möglichkeiten:

Wiederholen Sie diesen Vorgang für jeden Iframe im Dokument. Iframes können verschachtelt sein. Fügen Sie daher die Allow-Anweisung allen umliegenden übergeordneten Iframes hinzu.

Content Security Policy prüfen

Wenn auf Ihrer Website eine Content Security Policy verwendet wird, müssen Sie sie möglicherweise aktualisieren, damit die Google Sign-in-Bibliothek verwendet werden kann.

Folgen Sie der Anleitung unter Anfrage der Google Sign-in-Bibliothek finden, wählen Sie die Anfrage der Google Sign-in-Bibliothek im DevTools-Bereich Netzwerk aus und suchen Sie auf dem Tab Header im Bereich Antwortheader nach dem Header Content-Security-Policy.

Wenn der Header nicht gefunden wird, sind keine Änderungen erforderlich. Andernfalls prüfen Sie, ob eine dieser CSP-Anweisungen im CSP-Header definiert ist, und aktualisieren Sie sie so:

  • https://apis.google.com/js/, https://accounts.google.com/gsi/ und https://acounts.google.com/o/fedcm/ zu connect-src-, default-src- oder frame-src-Anweisungen hinzufügen

  • Fügen Sie der script-src-Anweisung https://apis.google.com/js/bundle-name.js hinzu. Ersetzen Sie bundle-name.js durch api.js, client.js oder platform.js, je nachdem, welches Bibliothekspaket die Dokumentanfragen enthält.

Änderungen an Nutzeraufforderungen prüfen

Es gibt einige Unterschiede beim Verhalten von Nutzeraufforderungen. FedCM fügt ein modales Dialogfeld hinzu, das vom Browser angezeigt wird, und aktualisiert die Anforderungen für die Nutzeraktivierung.

Bild des modalen Dialogfelds von FedCM

Prüfen Sie das Layout Ihrer Website, um sicherzustellen, dass die zugrunde liegenden Inhalte sicher überlagert und vorübergehend durch das modale Dialogfeld des Browsers verdeckt werden können. Andernfalls müssen Sie möglicherweise das Layout oder die Position einiger Elemente Ihrer Website anpassen.

Nutzeraktivierung

FedCM enthält aktualisierte Anforderungen für die Nutzeraktivierung. Das Drücken einer Schaltfläche oder das Klicken auf einen Link sind Beispiele für Nutzeraktionen, die es Drittanbietern ermöglichen, Netzwerkanfragen zu stellen oder Daten zu speichern. Bei FedCM fordert der Browser die Nutzereinwilligung in folgenden Fällen an:

  • ein Nutzer sich zum ersten Mal mit einer neuen Browserinstanz in einer Webanwendung anmeldet oder
  • GoogleAuth.signIn wird aufgerufen.

Wenn sich der Nutzer bereits auf Ihrer Website angemeldet hat, können Sie die Anmeldedaten des Nutzers beim Initialisieren der Google Sign-In-Bibliothek mit gapi.auth2.init abrufen, ohne dass der Nutzer weitere Aktionen ausführen muss. Das ist nicht mehr möglich, es sei denn, der Nutzer hat die FedCM-Anmeldeabfolge mindestens einmal durchlaufen.

Wenn Sie FedCM aktivieren und GoogleAuth.signIn aufrufen, kann gapi.auth2.init beim nächsten Besuch desselben Nutzers auf Ihrer Website die Anmeldeinformationen des Nutzers während der Initialisierung abrufen, ohne dass der Nutzer etwas tun muss.

Gängige Anwendungsfälle

Die Entwicklerdokumentation für die Google Sign-In-Bibliothek enthält Anleitungen und Codebeispiele für gängige Anwendungsfälle. In diesem Abschnitt wird erläutert, wie sich FedCM auf ihr Verhalten auswirkt.

  • Google Log-in in Ihre Webanwendung einbinden

    In dieser Demo wird die Schaltfläche mit einem <div>-Element und einer Klasse gerendert. Bei bereits angemeldeten Nutzern gibt das Ereignis „Seiten-onload“ die Nutzeranmeldedaten zurück. Für die Anmeldung und Einrichtung einer neuen Sitzung ist eine Nutzerinteraktion erforderlich.

    Die Bibliothek wird von der Klasse g-signin2 initialisiert, die gapi.load und gapi.auth2.init aufruft.

    Eine Nutzergeste, ein <div>-Element-onclick-Ereignis, ruft auth2.signIn während der Anmeldung oder auth2.signOut bei der Abmeldung auf.

  • Benutzerdefinierte Schaltfläche für Google Log-in erstellen

    In Demo 1 wird das Aussehen der Anmeldeschaltfläche mithilfe von benutzerdefinierten Attributen gesteuert. Bei bereits angemeldeten Nutzern gibt das Ereignis „Seite onload“ die Anmeldedaten des Nutzers zurück. Für die Anmeldung und Einrichtung einer neuen Sitzung ist eine Nutzerinteraktion erforderlich.

    Die Bibliothek wird über ein onload-Ereignis für die platform.js-Bibliothek initialisiert und die Schaltfläche wird von gapi.signin2.render angezeigt.

    Durch eine Nutzergeste, bei der die Anmeldeschaltfläche gedrückt wird, wird auth2.signIn aufgerufen.

    In Demo 2 werden ein <div>-Element, CSS-Stile und eine benutzerdefinierte Grafik verwendet, um das Erscheinungsbild der Anmeldeschaltfläche zu steuern. Für die Anmeldung und Einrichtung einer neuen Sitzung ist eine Nutzerinteraktion erforderlich.

    Die Bibliothek wird beim Laden des Dokuments mit einer Startfunktion initialisiert, die gapi.load, gapi.auth2.init und gapi.auth2.attachClickHandler aufruft.

    Eine Nutzergeste, ein <div>-Element-onclick-Ereignis, ruft auth2.signIn mithilfe von auth2.attachClickHandler während der Anmeldung oder auth2.signOut bei der Abmeldung auf.

  • Sitzungsstatus des Nutzers überwachen

    In dieser Demo wird zum Anmelden und Abmelden des Nutzers eine Schaltfläche verwendet. Für die Anmeldung und Einrichtung einer neuen Sitzung ist eine Nutzerinteraktion erforderlich.

    Die Bibliothek wird durch direkten Aufruf von gapi.load, gapi.auth2.init und gapi.auth2.attachClickHandler() initialisiert, nachdem platform.js mit script src geladen wurde.

    Eine Nutzergeste, ein <div>-Element-onclick-Ereignis, ruft auth2.signIn mithilfe des auth2.attachClickHandler während der Anmeldung oder auth2.signOut bei der Abmeldung auf.

  • Zusätzliche Berechtigungen anfordern

    In dieser Demo wird durch Drücken einer Schaltfläche eine zusätzliche OAuth 2.0-Berechtigung angefordert, um ein neues Zugriffstoken zu erhalten. Bei bereits angemeldeten Nutzern werden über das Ereignis „Seite onload“ Nutzeranmeldedaten zurückgegeben. Für die Anmeldung und Einrichtung einer neuen Sitzung ist eine Nutzerinteraktion erforderlich.

    Die Bibliothek wird durch das onload-Ereignis für die platform.js-Bibliothek über einen Aufruf von gapi.signin2.render initialisiert.

    Wenn ein Nutzer auf ein <button>-Element klickt, wird beim Abmelden eine Anfrage für zusätzliche OAuth 2.0-Anwendungsbereiche mit googleUser.grant oder auth2.signOut ausgelöst.

  • Google Sign-In mit Listenern einbinden

    In dieser Demo werden für bereits angemeldete Nutzer über das Ereignis „Seite onload“ Nutzeranmeldedaten zurückgegeben. Für die Anmeldung und Einrichtung einer neuen Sitzung ist eine Nutzerinteraktion erforderlich.

    Die Bibliothek wird beim Laden des Dokuments mit einer Startfunktion initialisiert, die gapi.load, gapi.auth2.init und gapi.auth2.attachClickHandler aufruft. Als Nächstes werden auth2.isSignedIn.listen und auth2.currentUser.listen verwendet, um Benachrichtigungen zu Änderungen am Sitzungsstatus einzurichten. Schließlich wird auth2.SignIn aufgerufen, um Anmeldedaten für angemeldete Nutzer zurückzugeben.

    Eine Nutzergeste, ein <div>-Element-onclick-Ereignis, ruft auth2.signIn mithilfe von auth2.attachClickHandler während der Anmeldung oder auth2.signOut bei der Abmeldung auf.

  • Google Log-in für serverseitige Apps

    In dieser Demo wird ein Nutzer-Geste verwendet, um einen OAuth 2.0-Authentifizierungscode anzufordern. Ein JS-Callback führt einen AJAX-Aufruf aus, um die Antwort zur Überprüfung an den Backend-Server zu senden.

    Die Bibliothek wird mit einem onload-Ereignis für die platform.js-Bibliothek initialisiert, bei dem gapi.load und gapi.auth2.init über eine Startfunktion aufgerufen werden.

    Wenn ein Nutzer auf ein <button>-Element klickt, wird durch Aufrufen von auth2.grantOfflineAccess eine Anfrage für einen Autorisierungscode ausgelöst.

  • Plattformübergreifende SSO

    Für FedCM ist eine Einwilligung für jede Browserinstanz erforderlich. Auch wenn Android-Nutzer bereits angemeldet sind, ist eine einmalige Einwilligung erforderlich.

Übergangszeit verwalten

Während der Umstellungsphase wird für einen Teil der Nutzeranmeldungen möglicherweise FedCM verwendet. Der genaue Prozentsatz kann variieren und sich im Laufe der Zeit ändern. Standardmäßig steuert Google, wie viele Anmeldeanfragen FedCM verwenden. Sie können die Verwendung von FedCM jedoch während der Übergangsphase aktivieren oder deaktivieren. Am Ende der Übergangsphase wird FedCM obligatorisch und für alle Anmeldeanfragen verwendet.

Wenn du die Funktion aktivierst, wird der Nutzer durch den FedCM-Anmeldevorgang geführt. Wenn du sie deaktivierst, wird der Nutzer durch den vorhandenen Anmeldevorgang geführt. Dieses Verhalten wird mit dem Parameter use_fedcm gesteuert.

Opt-in

Es kann hilfreich sein, festzulegen, ob alle oder einige Anmeldeversuche auf Ihrer Website FedCM APIs verwenden sollen. Dazu musst du use_fedcm auf true setzen, wenn du die Plattformbibliothek initialisierst. Für die Nutzeranmeldung werden in diesem Fall FedCM APIs verwendet.

Deaktivieren

Während der Übergangsphase werden bei einem Prozentsatz der Anmeldeversuche auf Ihrer Website standardmäßig FedCM APIs verwendet. Wenn Sie mehr Zeit für Änderungen an Ihrer App benötigen, können Sie die Verwendung von FedCM APIs vorübergehend deaktivieren. Dazu setzt du use_fedcm auf false, wenn du die Plattformbibliothek initialisierst. Für die Nutzeranmeldung werden in diesem Fall keine FedCM APIs verwendet.

Nach der obligatorischen Einführung werden alle use_fedcm-Einstellungen von der Google Sign-in-Plattformbibliothek ignoriert.

Hilfe

Mit dem Tag google-signin können Sie auf Stack Overflow nach Antworten suchen oder Fragen stellen.