Logowanie przez Google przez interfejsy API FedCM

W tym przewodniku omawiamy wdrażanie interfejsów API FedCM przez bibliotekę platformy logowania Google. Tematy obejmują Harmonogram i Kolejne kroki dotyczące aktualizacji biblioteki z zachowaniem zgodności wstecznej, przeprowadzenia oceny wpływu oraz weryfikacji, czy logowanie użytkownika nadal działa zgodnie z oczekiwaniami. W razie potrzeby znajdziesz też instrukcje dotyczące aktualizowania aplikacji internetowej. Omówione są też opcje zarządzania okresem przejściowym oraz sposób uzyskiwania pomocy.

Stan biblioteki

Wszystkie nowe aplikacje internetowe nie będą mogły korzystać z wycofanej biblioteki platformy logowania Google. Aplikacje korzystające z tej biblioteki mogą jednak korzystać z niej do odwołania. Nie ustalono ostatecznej daty wycofania (wyłączenia) biblioteki. Więcej informacji znajdziesz w artykule Wycofanie obsługi i zakończenie obsługi funkcji.

Aktualizacja zgodna wstecznie dodaje interfejsy API FedCM do biblioteki Logowania przez Google. Większość zmian jest płynna, ale aktualizacja wprowadza różnice w prośbach kierowanych do użytkowników, polityce dostępu w ramkach iframe oraz polityce Content Security Policy (CSP). Te zmiany mogą mieć wpływ na Twoją aplikację internetową i wymagać wprowadzenia zmian w kodzie aplikacji i konfiguracji witryny.

W okresie przejściowym opcja konfiguracji określa, czy interfejsy FedCM mają być używane podczas logowania użytkownika.

Po zakończeniu okresu przejściowego interfejsy FedCM będą wymagane we wszystkich aplikacjach internetowych korzystających z biblioteki Logowania Google.

Oś czasu

Ostatnia aktualizacja: wrzesień 2024 r.

Oto daty i zmiany, które mają wpływ na logowanie użytkowników:

  • Marzec 2023 r. Wycofanie obsługi biblioteki platformy Google Sign-In.
  • Rozpoczyna się okres przejściowy w lipcu 2024 r. i dodawana jest obsługa interfejsów FedCM w bibliotece platformy Zaloguj się przez Google. Domyślnie w tym czasie Google kontroluje odsetek żądań logowania się użytkowników za pomocą FedCM. Aplikacje internetowe mogą wyraźnie zastąpić to zachowanie za pomocą parametru use_fedcm.
  • Marzec 2025 r. – obowiązkowe wdrożenie interfejsów API FedCM przez bibliotekę platformy logowania Google. Po tym terminie parametr use_fedcm zostanie zignorowany, a wszystkie żądania logowania użytkownika będą korzystać z FedCM.

Dalsze kroki

Masz do wyboru 3 opcje:

  1. Przeprowadź ocenę wpływu i w razie potrzeby zaktualizuj aplikację internetową. W ramach tego podejścia sprawdzasz, czy są używane funkcje, które wymagają wprowadzenia zmian w aplikacji internetowej. Instrukcje znajdziesz w następnej sekcji tego przewodnika.
  2. Przenieś bibliotekę Google Identity Services (GIS). Zdecydowanie zalecamy przejście do najnowszej i obsługiwanej biblioteki logowania. Aby to zrobić, wykonaj te instrukcje.
  3. Nic nie rób. Twoja aplikacja internetowa zostanie automatycznie zaktualizowana, gdy biblioteka logowania Google przejdzie na interfejsy API FedCM do logowania użytkowników. To najmniej wymagające rozwiązanie, ale istnieje ryzyko, że użytkownicy nie będą mogli zalogować się w aplikacji internetowej.

Ocena wpływu

Wykonaj te instrukcje, aby sprawdzić, czy Twoją aplikację internetową można bezproblemowo zaktualizować przez aktualizację zgodną wstecznie, czy konieczne są zmiany, które uniemożliwią użytkownikom logowanie się, gdy biblioteka platformy logowania Google w pełni wdroży interfejsy API FedCM.

Konfiguracja

Aby korzystać z FedCM podczas logowania użytkownika, musisz użyć interfejsów API przeglądarki i najnowszej wersji biblioteki platformy Google Sign-In.

Zanim przejdziesz dalej:

  • Zaktualizuj Chrome na komputer do najnowszej wersji. Chrome na Androida wymaga wersji M128 lub nowszej i nie można jej testować przy użyciu wcześniejszych wersji.

  • Otwórz chrome://flags i ustaw te funkcje na te wartości:

    • #fedcm-authz Włączono
    • #tracking-protection-3pcd Włączono
    • #third-party-cookie-deprecation-trial Disabled
    • #tpcd-metadata-grants Wyłączone
    • #tpcd-heuristics-grants Wyłączone

    i ponownie uruchom Chrome.

  • Podczas inicjowania biblioteki platformy logowania Google w aplikacji internetowej ustaw parametr use_fedcm na true. Zazwyczaj inicjalizacja wygląda tak:

    • gapi.client.init({use_fedcm: true}) lub
    • gapi.auth2.init({use_fedcm: true}) lub
    • gapi.auth2.authorize({use_fedcm: true}).

  • Unieważnianie wersji biblioteki platformy Google Sign-In w pamięci podręcznej. Zazwyczaj ten krok nie jest potrzebny, ponieważ najnowsza wersja biblioteki jest pobierana bezpośrednio do przeglądarki przez uwzględnienie w tagu <script src> wartości api.js, client.js lub platform.js (żądanie może używać dowolnej z tych nazw pakietu biblioteki).

  • Potwierdź ustawienia OAuth dla identyfikatora klienta OAuth:

    1. Otwórz stronę Dane logowania w  Google API Console

    2. Sprawdź, czy identyfikator URI Twojej witryny znajduje się w sekcji Autoryzowane źródła JavaScriptu. Identyfikator URI zawiera tylko schemat i w pełni kwalifikowaną nazwę hosta. Na przykład: https://www.example.com.

    3. Opcjonalnie dane logowania mogą być zwracane za pomocą przekierowania do punktu końcowego hostowanego przez Ciebie zamiast wywołania zwrotnego JavaScript. W takim przypadku sprawdź, czy identyfikatory URI przekierowania są uwzględnione w autoryzowanych identyfikatorach URI przekierowania. Identyfikatory URI przekierowania zawierają schemat, pełną nazwę hosta i ścieżkę. Muszą być zgodne z regułami sprawdzania identyfikatorów URI przekierowania. Na przykład: https://www.example.com/auth-receiver.

Testowanie

Po wykonaniu instrukcji konfiguracji:

Znajdowanie żądania biblioteki logowania w Google

Sprawdź, czy zmiany w Permissions-Policy i Content Security Policy są konieczne, sprawdzając prośbę o bibliotekę platformy logowania w Google. Aby to zrobić, znajdź żądanie, korzystając z nazwy i źródła biblioteki:

  • W Chrome otwórz panel Sieć w Narzędziach deweloperskich i załaduj ponownie stronę.
  • Aby znaleźć bibliotekę, użyj wartości w kolumnach Domena i Nazwa:
    • Domena to apis.google.com, a
    • Nazwa to api.js, client.js lub platform.js. Konkretna wartość nazwy zależy od pakietu biblioteki określonego w dokumencie.

Na przykład zastosuj filtr apis.google.com w kolumnie Domena i platform.js w kolumnie Nazwa.

Sprawdzanie uprawnień iframe-policy

Twoja witryna może używać biblioteki platformy Logowanie przez Google w ramach elementu iframe z dostępem do wielu witryn. Jeśli tak, konieczna będzie aktualizacja.

Po wykonaniu instrukcji Znajdowanie żądania biblioteki funkcji logowania Google wybierz żądanie biblioteki funkcji logowania Google w panelu Sieć w DevTools i odszukaj nagłówek Sec-Fetch-Site w sekcji Nagłówki żądania na karcie Nagłówki. Jeśli wartość nagłówka jest:

  • Jeśli same-site lub same-origin, zasady dotyczące wielu źródeł nie obowiązują i nie trzeba wprowadzać żadnych zmian.
  • Jeśli używany jest element iframe, konieczne może być wprowadzenie zmian w elemencie cross-origin.

Aby sprawdzić, czy element iframe jest obecny:

  • W Narzędziach deweloperskich Chrome wybierz panel Elementy.
  • Aby znaleźć element iframe w dokumencie, naciśnij klawisze Ctrl + F.

Jeśli zostanie znaleziony iframe, sprawdź dokument pod kątem wywołań funkcji gapi.auth2 lub dyrektyw script src, które ładują bibliotekę funkcji logowania Google w ramach iframe. W takim przypadku:

Powtórz ten proces w przypadku każdego elementu iframe w dokumencie. Elementy iframe mogą być zagnieżdżone, więc pamiętaj, aby dodać dyrektywę allow do wszystkich otoczonych przez nie elementów iframe.

Sprawdzanie Content Security Policy

Jeśli Twoja witryna korzysta z standardu Content Security Policy, konieczne może być zaktualizowanie tego standardu, aby zezwalał na korzystanie z biblioteki funkcji logowania Google.

Po wykonaniu instrukcji Znajdowanie żądania biblioteki funkcji logowania Google wybierz żądanie biblioteki funkcji logowania Google w panelu Sieć w DevTools i odszukaj nagłówek Content-Security-Policy w sekcji Nagłówki odpowiedzi na karcie Nagłówki.

Jeśli nagłówek nie został znaleziony, nie są wymagane żadne zmiany. W przeciwnym razie sprawdź, czy w nagłówku CSP zdefiniowano którąś z tych dyrektyw CSP, i zaktualizuj je, wykonując te czynności:

  • Dodanie poleceń https://apis.google.com/js/, https://accounts.google.com/gsi/ i https://acounts.google.com/o/fedcm/ do dowolnego polecenia connect-src, default-src lub frame-src.

  • Dodaję polecenie https://apis.google.com/js/bundle-name.js do dyrektywy script-src. Zastąp bundle-name.js wartością api.js, client.js lub platform.js w zależności od pakietu biblioteki, do którego należą żądane dokumenty.

Sprawdzanie, czy nie zmieniły się prośby użytkowników

Istnieją pewne różnice w zachowaniu prompta użytkownika. FedCM dodaje okno modalne wyświetlane przez przeglądarkę i aktualizuje wymagania dotyczące aktywacji użytkownika.

Obraz okna modalnego FedCM

Sprawdź układ witryny, aby upewnić się, że zawartość podstawowa może być bezpiecznie nałożona i tymczasowo zasłonięta przez okno modalne przeglądarki. Jeśli tak nie jest, konieczne może być dostosowanie układu lub położenia niektórych elementów witryny.

Aktywacja użytkownika

FedCM obejmuje zaktualizowane wymagania dotyczące aktywacji użytkownika. Naciśnięcie przycisku lub kliknięcie linku to przykłady gestów użytkownika, które umożliwiają zewnętrznym źródłom wysyłanie żądań sieciowych lub przechowywanie danych. W przypadku FedCM przeglądarka prosi o zgodę użytkownika, gdy:

  • użytkownik po raz pierwszy loguje się w aplikacji internetowej przy użyciu nowego wystąpienia przeglądarki;
  • Funkcja GoogleAuth.signIn jest wywoływana.

Obecnie, jeśli użytkownik wcześniej logował się w Twojej witrynie, możesz uzyskać jego dane logowania podczas inicjowania biblioteki Logowania przez Google za pomocą gapi.auth2.init bez dalszych interakcji z użytkownikiem. Nie jest to już możliwe, chyba że użytkownik przynajmniej raz przeszedł proces logowania FedCM.

Gdy włączysz FedCM i wywołasz funkcję GoogleAuth.signIn, następnym razem, gdy ten sam użytkownik odwiedzi Twoją witrynę, funkcja gapi.auth2.init może uzyskać informacje o zalogowaniu użytkownika podczas inicjalizacji bez jego udziału.

Częste zastosowania

Dokumentacja dla deweloperów dotycząca biblioteki Logowania w Google zawiera przewodniki i próbki kodu dla typowych zastosowań. W tej sekcji omawiamy wpływ FedCM na ich zachowanie.

  • Integracja Logowania przez Google z aplikacją internetową

    W tej wersji demonstracyjnej przycisk <div> i klasa renderują przycisk, a w przypadku już zalogowanych użytkowników zdarzenie onload zwraca dane logowania użytkownika. Aby zalogować się i utworzyć nową sesję, użytkownik musi podjąć działanie.

    Inicjalizacja biblioteki jest wykonywana przez klasę g-signin2, która wywołuje funkcje gapi.load i gapi.auth2.init.

    Gest użytkownika, zdarzenie <div> elementu onclick, wywołuje funkcję auth2.signIn podczas logowania się lub auth2.signOut podczas wylogowywania się.

  • Tworzenie niestandardowego przycisku logowania w Google

    W pierwszym pokazie demonstracyjnym atrybuty niestandardowe służą do kontrolowania wyglądu przycisku logowania, a w przypadku zalogowanych już użytkowników zdarzenie strony onload zwraca dane logowania użytkownika. Do zalogowania się i zainicjowania nowej sesji wymagana jest interakcja użytkownika.

    Inicjowanie biblioteki odbywa się za pomocą zdarzenia onload dla biblioteki platform.js, a przycisk jest wyświetlany przez gapi.signin2.render.

    Gest użytkownika, czyli naciśnięcie przycisku logowania, wywołuje funkcję auth2.signIn.

    W wersji demonstracyjnej 2 do sterowania wyglądem przycisku logowania służą element <div>, style CSS i niestandardowa grafika. Aby zalogować się i utworzyć nową sesję, użytkownik musi podjąć działanie.

    Inicjalizacja biblioteki jest wykonywana podczas wczytywania dokumentu za pomocą funkcji start, która wywołuje funkcje gapi.load, gapi.auth2.init i gapi.auth2.attachClickHandler.

    Gest użytkownika, zdarzenie elementu <div> onclick, wywołuje auth2.signIn za pomocą auth2.attachClickHandler podczas logowania lub auth2.signOut podczas wylogowywania.

  • Monitorowanie stanu sesji użytkownika

    W tej wersji demonstracyjnej do logowania i wylogowywania się użytkownika służy naciśnięcie przycisku. Aby zalogować się i utworzyć nową sesję, użytkownik musi podjąć działanie.

    Inicjowanie biblioteki odbywa się bezpośrednio przez wywołanie gapi.load, gapi.auth2.init i gapi.auth2.attachClickHandler() po wczytaniu biblioteki platform.js za pomocą script src.

    Gest użytkownika, zdarzenie elementu <div> onclick, wywołuje auth2.signIn za pomocą auth2.attachClickHandler podczas logowania lub auth2.signOut podczas wylogowywania.

  • Prośba o dodatkowe uprawnienia

    W tym demo naciśnięcie przycisku służy do żądania dodatkowych zakresów uprawnień OAuth 2.0, uzyskania nowego tokena dostępu, a w przypadku zalogowanych już użytkowników do zwracania danych logowania użytkownika w zdarzeniu strony onload. Aby zalogować się i utworzyć nową sesję, użytkownik musi podjąć działanie.

    Inicjowanie biblioteki jest wykonywane przez zdarzenie onload dla biblioteki platform.js poprzez wywołanie gapi.signin2.render.

    Gest użytkownika, czyli kliknięcie elementu <button>, powoduje wysłanie żądania dodatkowego zakresu OAuth 2.0 za pomocą googleUser.grant lub auth2.signOut podczas wylogowywania.

  • Integracja logowania się przez Google za pomocą metody Listener

    W tym demo w przypadku zalogowanych użytkowników zdarzenie page onload zwraca dane logowania użytkownika. Aby zalogować się i utworzyć nową sesję, użytkownik musi podjąć działanie.

    Inicjalizacja biblioteki jest wykonywana podczas wczytywania dokumentu za pomocą funkcji start, która wywołuje funkcje gapi.load, gapi.auth2.init i gapi.auth2.attachClickHandler. Następnie parametry auth2.isSignedIn.listen i auth2.currentUser.listen służą do konfigurowania powiadomień o zmianach stanu sesji. Na koniec wywoływana jest funkcja auth2.SignIn, która zwraca dane logowania zalogowanych użytkowników.

    Gest użytkownika, zdarzenie elementu <div> onclick, wywołuje auth2.signIn za pomocą auth2.attachClickHandler podczas logowania lub auth2.signOut podczas wylogowywania.

  • Logowanie przez Google w aplikacjach po stronie serwera

    W tej wersji demonstracyjnej gest użytkownika jest używany do żądania kodu autoryzacji OAuth 2.0, a wywołanie zwrotne JS wykonuje wywołanie AJAX w celu wysłania odpowiedzi do serwera backendu w celu weryfikacji.

    Inicjalizacja biblioteki jest wykonywana za pomocą zdarzenia onload biblioteki platform.js, która używa funkcji start do wywołania funkcji gapi.load i gapi.auth2.init.

    Gest użytkownika, czyli kliknięcie elementu <button>, powoduje wysłanie żądania kodu autoryzacji przez wywołanie funkcji auth2.grantOfflineAccess.

  • Logowanie jednokrotne na wielu platformach

    FedCM wymaga zgody dla każdej instancji przeglądarki, nawet jeśli użytkownicy Androida są już zalogowani. Konieczna jest jednorazowa zgoda.

Zarządzanie okresem przejściowym

W okresie przejściowym pewien odsetek logowań użytkowników może korzystać z FedCM. Dokładny odsetek może się różnić i zmieniać w czasie. Domyślnie Google kontroluje, ile żądań logowania korzysta z FedCM, ale w okresie przejściowym możesz włączyć lub wyłączyć korzystanie z FedCM. Pod koniec okresu przejściowegoFedCM stanie się obowiązkowy i będzie używany we wszystkich żądaniach logowania.

Gdy zgodzisz się na to, użytkownik musi przejść przez proces logowania w FedCM, a zrezygnować, musi przejść przez bieżący proces logowania. To zachowanie jest kontrolowane za pomocą parametru use_fedcm.

Zaakceptuj

Możesz określić, czy wszystkie czy tylko niektóre próby logowania się na stronie mają używać interfejsów FedCM. Aby to zrobić, podczas inicjowania biblioteki platformy ustaw wartość use_fedcm na true. W tym przypadku żądanie logowania użytkownika korzysta z interfejsów FedCM.

Rezygnacja

W okresie przejściowym określony odsetek prób zalogowania się w Twojej witrynie będzie domyślnie korzystać z interfejsów API FedCM. Jeśli potrzebujesz więcej czasu na wprowadzenie zmian w aplikacji, możesz tymczasowo zrezygnować z korzystania z interfejsów FedCM API. Aby to zrobić, ustaw use_fedcm na false podczas inicjowania biblioteki platformy. W tym przypadku żądanie zalogowania użytkownika nie będzie korzystać z interfejsów API FedCM.

Po obowiązkowym wdrożeniu wszystkie ustawienia use_fedcm są ignorowane przez bibliotekę platformy logowania Google.

Pomoc

Wyszukaj informacje lub zadaj pytania na StackOverflow, używając tagu google-signin.