Google Log-in mit FedCM APIs

In diesem Leitfaden wird die Verwendung von FedCM APIs durch die Google Sign-in-Plattformbibliothek beschrieben. Unter anderem werden die Zeitachse und die nächsten Schritte für ein abwärtskompatibles Update der Bibliothek, die Durchführung einer Wirkungsanalyse und die Überprüfung der Nutzeranmeldung weiterhin wie erwartet funktionieren, sowie bei Bedarf Anleitungen zum Aktualisieren Ihrer Web-App. Optionen zum Verwalten der Übergangsphase und dazu, wie Sie Hilfe aufrufen, werden ebenfalls 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 erfordern Änderungen am Anwendungscode und der Websitekonfiguration.

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 Webanwendungen obligatorisch, die die Google Log-in-Bibliothek verwenden.

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 den Prozentsatz der Anmeldeanfragen von Nutzern über FedCM während dieser Zeit. Web-Apps können dieses Verhalten mit dem Parameter use_fedcm explizit überschreiben.
  • März 2025: Einführung der FedCM APIs in der Google Sign-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). Es wird dringend empfohlen, zur neuesten und unterstützten Anmeldebibliothek zu wechseln. Folgen Sie dazu dieser Anleitung.
  3. Nichts unternehmen: Ihre Webanwendung wird automatisch aktualisiert, wenn die Google Log-in-Bibliothek für die Nutzeranmeldung zu FedCM APIs verschoben wird. Das ist zwar die geringste Arbeit, es besteht jedoch das Risiko, dass sich Nutzer nicht in Ihrer Webanwendung anmelden können.

Folgenabschätzung durchführen

Befolge diese Anleitung, um festzustellen, ob deine Webanwendung durch ein abwärtskompatibles Update nahtlos aktualisiert werden kann oder ob Änderungen erforderlich sind, damit sich Nutzer nicht anmelden können, wenn die Google Log-in-Plattformbibliothek FedCM APIs vollständig unterstützt.

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.

  • Öffnen Sie chrome://flags und legen Sie für die folgenden Funktionen die folgenden Werte fest:

    • #fedcm-authz aktiviert
    • #tracking-protection-3pcd Aktiviert
    • #third-party-cookie-deprecation-trial Deaktiviert
    • #tpcd-metadata-grants Deaktiviert
    • #tpcd-heuristics-grants Deaktiviert

    und starten Sie Chrome neu.

  • Legen Sie use_fedcm auf true fest, wenn Sie die Plattformbibliothek für die Google Sign-in-Plattform 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 Google API Console

    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 in der Spalte Domain nach apis.google.com und in der Spalte Name nach platform.js.

iFrame-Berechtigungsrichtlinie prüfen

Auf Ihrer Website wird möglicherweise die Google Log-in-Plattformbibliothek in einem ursprungsü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 alle iFrames im Dokument. iFrames können verschachtelt sein. Achten Sie daher darauf, die „allow“-Anweisung zu allen umgebenden übergeordneten iFrames hinzuzufügen.

Content Security Policy prüfen

Wenn für deine Website eine Content Security Policy verwendet wird, musst du möglicherweise deine CSP aktualisieren, damit die Google Log-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 integrieren

    In dieser Demo rendern ein <div>-Element und eine Klasse die Schaltfläche. Für bereits angemeldete Nutzer gibt das Ereignis der Seite onload 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 onclick-Ereignis des <div>-Elements, ruft bei der Anmeldung auth2.signIn oder beim Abmelden auth2.signOut 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“ Nutzeranmeldedaten 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 zwei werden ein <div>-Element, CSS-Stile und eine benutzerdefinierte Grafik verwendet, um die Darstellung der Anmeldeschaltfläche zu steuern. Für die Anmeldung und Einrichtung einer neuen Sitzung ist eine Nutzerinteraktion erforderlich.

    Die Initialisierung der Bibliothek erfolgt beim Laden des Dokuments mithilfe einer Startfunktion, 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 das Erstellen einer neuen Sitzung ist eine Nutzerinteraktion erforderlich.

    Zur Initialisierung der Bibliothek werden gapi.load, gapi.auth2.init und gapi.auth2.attachClickHandler() direkt aufgerufen, 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 das Erstellen einer neuen Sitzung ist eine Nutzerinteraktion erforderlich.

    Die Initialisierung der Bibliothek erfolgt über das Ereignis onload für die Bibliothek platform.js über einen Aufruf von gapi.signin2.render.

    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 Log-in mit Hörern einbinden

    In dieser Demo werden für bereits angemeldete Nutzer über das Ereignis „Seite onload“ Nutzeranmeldedaten zurückgegeben. Für die Anmeldung und das Starten 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 Initialisierung der Bibliothek erfolgt mit einem onload-Ereignis für die Bibliothek platform.js, das eine Startfunktion zum Aufrufen von gapi.load und gapi.auth2.init verwendet.

    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 die 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 über den 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.