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

Nowe aplikacje internetowe nie mogą korzystać z wycofanej biblioteki platformy logowania Google, ale aplikacje, które z niej korzystają, mogą to robić do odwołania. Nie ustalono ostatecznej daty zakończenia korzystania z biblioteki. Więcej informacji znajdziesz w artykule Wycofanie obsługi i zakończenie obsługi funkcji.

Zgodna wstecznie aktualizacja dodaje do biblioteki logowania w Google interfejsy FedCM API. 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 okresie przejściowym interfejsy FedCM będą obowiązkowe we wszystkich aplikacjach internetowych korzystających z biblioteki Logowania Google.

Oś czasu

Ostatnia aktualizacja: wrzesień 2024 r.

Oto daty i zmiany, które wpływają na sposób logowania się 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 przez 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 na najnowszą i obsługiwaną bibliotekę 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.

Przeprowadzanie oceny wpływu

Postępuj zgodnie z tymi instrukcjami, aby ustalić, czy aplikacja internetowa może być bezproblemowo aktualizowana za pomocą aktualizacji zgodnej z wsteczoną lub czy konieczne są zmiany, aby użytkownicy mogli się zalogować, gdy biblioteka platformy logowania Google wprowadzi pełną obsługę interfejsów 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 komputerze do najnowszej wersji. Chrome na Androida wymaga wersji M128 lub nowszej i nie można go testować w wersjach starszych.
  • Podczas inicjowania biblioteki platformy Logowania w Google w aplikacji internetowej ustaw wartość use_fedcm na true. Typowa 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 tagu api.js, client.js lub platform.js w tagu <script src> (żą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. Adres URI zawiera tylko schemat i właściwą 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 ponownie załaduj 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.

Ustaw na przykład 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.
  • cross-originw razie używania ramki iframe może być konieczne wprowadzenie zmian.

Aby sprawdzić, czy element iframe jest obecny:

  • W Narzędziach deweloperskich Chrome wybierz panel Elementy.
  • Aby znaleźć w dokumencie iframe, użyj skrótu 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 nie znajdziesz nagłówka, nie musisz nic zmieniać. 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ę 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 zmian w prośbach kierowanych do użytkownika

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

Okno modalne 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 działań użytkownika, które umożliwiają źródłom zewnętrznym wysyłanie żądań sieciowych lub przechowywanie danych. W ramach 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 logował się wcześniej w Twojej witrynie, możesz uzyskać jego dane logowania podczas inicjowania biblioteki logowania Google za pomocą funkcji gapi.auth2.init, bez dalszej 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.

Typowe 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 działanie.

  • Integracja funkcji logowania się przez Google z aplikacją internetową

    W tym demo przycisk jest renderowany przez element <div> i klasę, a w przypadku zalogowanych użytkowników zdarzenie strony 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. Aby zalogować się i utworzyć nową sesję, użytkownik musi podjąć działanie.

    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 demo 2 element <div>, style CSS i grafika niestandardowa są używane do kontrolowania wyglądu przycisku logowania. 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 tym demo do logowania i wylogowywania użytkownika służy naciśnięcie przycisku. Aby zalogować się i utworzyć nową sesję, użytkownik musi podjąć działanie.

    Inicjalizowanie biblioteki odbywa się przez bezpośrednie wywołanie funkcji gapi.load, gapi.auth2.init i gapi.auth2.attachClickHandler() po załadowaniu 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 za pomocą wywołania funkcji gapi.signin2.render.

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

  • Integracja logowania się przez Google za pomocą listenerów

    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 w Google w przypadku aplikacji po stronie serwera

    W tym demo użyto gestu użytkownika, aby poprosić o kod autoryzacji OAuth 2.0, a wywołanie zwrotne JS wysyła żądanie AJAX, aby wysłać odpowiedź do serwera zaplecza 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 wywołanie funkcji auth2.grantOfflineAccess, która wysyła żądanie kodu autoryzacji.

  • 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.

Wybranie opcji akceptacji spowoduje przejście użytkownika przez proces logowania FedCM, a wybranie opcji odmowy spowoduje przejście użytkownika przez istnieją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 pewien odsetek prób logowania się użytkowników w Twojej witrynie będzie domyślnie używać interfejsów 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ć, podczas inicjowania biblioteki platformy ustaw wartość parametru use_fedcm na false. W tym przypadku żądanie logowania użytkownika nie będzie używać interfejsów 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.