Migracja z logowania przez Google

Ten przewodnik pomoże Ci zrozumieć niezbędne zmiany i kroki, które musisz wykonać, aby skutecznie przenieść biblioteki JavaScript ze starszej biblioteki platformy Google Sign-In do nowszej biblioteki Google Identity Services na potrzeby uwierzytelniania.

Jeśli Twój klient korzysta z biblioteki klienta interfejsu API Google dla JavaScript lub innych starszych bibliotek do autoryzacji, więcej informacji znajdziesz w artykule Migracja do usług Google Identity.

Uwierzytelnianie i autoryzacja

Uwierzytelnianie potwierdza tożsamość użytkownika i jest zwykle określane jako rejestracja lub logowanie. Autoryzacja to proces przyznawania lub odrzucania dostępu do danych lub zasobów. Na przykład aplikacja prosi użytkownika o zgodę na dostęp do jego Dysku Google.

Podobnie jak wcześniejsza biblioteka platformy Google Sign-In, nowa biblioteka Google Identity Services została stworzona z myślą o obsłudze procesów uwierzytelniania i autoryzacji.

Nowsza biblioteka rozdziela jednak te dwa procesy, aby uprościć deweloperom integrację kont Google z aplikacją.

Jeśli Twój przypadek użycia dotyczy tylko uwierzytelniania, czytaj dalej tę stronę.

Jeśli Twój przypadek użycia obejmuje autoryzację, przeczytaj artykuły Jak działa autoryzacja użytkownika i Migracja do usług Google Identity Services, aby upewnić się, że aplikacja korzysta z nowych i ulepszonych interfejsów API.

Co się zmieniło

Nowa biblioteka usług Google Identity Services oferuje użytkownikom wiele ulepszeń w zakresie użyteczności. Najważniejsze dodatkowe funkcje:

• Nowe, proste procesy logowania jednym dotknięciem i logowania automatycznego z mniejszą liczbą poszczególnych kroków.
• odświeżony przycisk logowania z personalizacją dla użytkownika,
• spójna marka i jednolite zachowanie podczas logowania w internecie zwiększają zrozumienie i zaufanie;
• szybko docierać do treści – użytkownicy mogą rejestrować się i logować bezpośrednio z dowolnego miejsca w Twojej witrynie bez konieczności odwiedzania strony logowania lub konta;

W przypadku deweloperów skupiliśmy się na zmniejszeniu złożoności, poprawie bezpieczeństwa i jak najszybszym wdrożeniu integracji. Oto niektóre z tych ulepszeń:

• możliwość dodania logowania użytkowników do statycznych treści witryny za pomocą samego kodu HTML,
• oddzielenie uwierzytelniania logowania od autoryzacji i udostępniania danych użytkownika, złożoność integracji OAuth 2.0 nie jest już konieczna do logowania użytkowników w Twojej witrynie,
• oba tryby (wyskakujący i przekierowania) są nadal obsługiwane, ale infrastruktura OAuth 2.0 Google przekierowuje teraz do punktu końcowego logowania na serwerze backendu,
• połączenie funkcji z obu wcześniejszych bibliotek JavaScript Google Identity i Google API w jedną nową bibliotekę;
• W przypadku odpowiedzi logowania możesz teraz zdecydować, czy chcesz używać Promise. Aby uprościć działanie, usunęliśmy też pośrednie wywołania funkcji w stylu getter.

Przykład przenoszenia logowania

Jeśli przechodzisz z dotychczasowego przycisku Logowanie przez Google i interesuje Cię tylko logowanie użytkowników w Twojej witrynie, najprostszym rozwiązaniem jest przejście na nowy spersonalizowany przycisk. Możesz to zrobić, zamieniając biblioteki JavaScript i aktualizując bazę kodu, aby używać nowego obiektu logowania.

Biblioteki i konfiguracja

Starsza biblioteka platformy Logowanie przez Google: apis.google.com/js/platform.js i biblioteka klienta interfejsów API Google w JavaScript: gapi.client nie są już wymagane do uwierzytelniania i autoryzacji użytkowników. Zostały one zastąpione jedną nową biblioteką JavaScriptu Google Identity Services:accounts.google.com/gsi/client.

Wcześniejsze 3 moduły JavaScript: api, client i platform używane do logowania są ładowane z apis.google.com. Aby pomóc Ci zidentyfikować miejsca, w których starsza biblioteka może być uwzględniona w Twojej witrynie, zwykle:

• domyślny przycisk logowania wczytuje się apis.google.com/js/platform.js,
• wczytuje się grafika niestandardowego przycisku apis.google.com/js/api:client.js,
• bezpośrednie użycie gapi.client powoduje wczytanie apis.google.com/js/api.js.

W większości przypadków możesz nadal używać dotychczasowych danych logowania identyfikatora klienta aplikacji internetowej. W ramach migracji zalecamy zapoznanie się z naszymi zasadami dotyczącymi OAuth 2.0 i użycie Konsoli interfejsów API Google, aby potwierdzić i w razie potrzeby zaktualizować te ustawienia klienta:

• aplikacje testowe i produkcyjne korzystają z osobnych projektów i mają własne identyfikatory klienta,
• typ identyfikatora klienta OAuth 2.0 to „Aplikacja internetowa”,
• W przypadku autoryzowanych źródeł JavaScript i identyfikatorów URI przekierowania używany jest protokół HTTPS.

Identyfikowanie kodu, którego dotyczy problem, i przeprowadzanie testów

Plik cookie debugowania może pomóc w zlokalizowaniu kodu, którego dotyczy problem, i w testowaniu działania po wycofaniu funkcji.

W przypadku dużych lub złożonych aplikacji znalezienie całego kodu, na który wpłynie wycofanie modułu gapi.auth2, może być trudne. Aby rejestrować w konsoli dotychczasowe użycie funkcji, które wkrótce zostaną wycofane, ustaw wartość pliku cookie G_AUTH2_MIGRATION na informational. Opcjonalnie możesz dodać dwukropek, a po nim wartość klucza, aby rejestrować dane także w pamięci sesji. Po zalogowaniu się i otrzymaniu danych logowania sprawdź je lub wyślij zebrane dzienniki do backendu w celu późniejszej analizy. Na przykład informational:showauth2use zapisuje źródło i adres URL w pamięci sesji pod kluczem o nazwie showauth2use.

Aby sprawdzić działanie aplikacji, gdy moduł gapi.auth2 nie jest już wczytywany, ustaw wartość pliku cookie G_AUTH2_MIGRATION na enforced. Umożliwia to testowanie zachowania po wycofaniu funkcji przed datą wejścia w życie zmian.

Możliwe wartości plików cookie G_AUTH2_MIGRATION:

• enforced Nie wczytuj modułu gapi.auth2.
• informational Rejestruj w konsoli JavaScriptu użycie wycofanych funkcji. Gdy ustawiona jest opcjonalna nazwa klucza, zapisz też dane w pamięci sesji:informational:key-name

Aby zminimalizować wpływ na użytkowników, zalecamy najpierw ustawić ten plik cookie lokalnie podczas programowania i testowania, a dopiero potem używać go w środowiskach produkcyjnych.

HTML i JavaScript

W tym scenariuszu logowania tylko w celu uwierzytelnienia pokazujemy przykładowy kod i renderowanie istniejącego przycisku logowania przez Google. Wybierz tryb wyskakującego okienka lub przekierowania, aby zobaczyć różnice w sposobie obsługi odpowiedzi uwierzytelniania przez wywołanie zwrotne JavaScript lub bezpieczne przekierowanie do punktu końcowego logowania na serwerze backendu.

Wcześniejszy sposób

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

Nowy sposób

Aby użyć nowej biblioteki w scenariuszu logowania tylko w celu uwierzytelnienia, wybierz tryb wyskakującego okienka lub przekierowania i użyj przykładowego kodu, aby zastąpić dotychczasową implementację na stronie logowania.

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

W tym przykładzie dotyczącym tylko uwierzytelniania nowa biblioteka accounts.google.com/gsi/client, klasa g_id_signin i obiekt g_id_onload zastępują wcześniejszą bibliotekę apis.google.com/js/platform.js i obiekt g-signin2.

Oprócz renderowania nowego spersonalizowanego przycisku przykładowy kod wyświetla też nowe wyskakujące okienko One Tap. W każdym miejscu, w którym wyświetlasz spersonalizowany przycisk, zalecamy też wyświetlanie wyskakującego okienka logowania jednym kliknięciem, aby zminimalizować trudności użytkowników podczas rejestracji i logowania.

Chociaż nie jest to zalecane ze względu na większe trudności z logowaniem, nowy spersonalizowany przycisk może być wyświetlany samodzielnie, bez jednoczesnego wyświetlania okna One Tap. Aby to zrobić, ustaw atrybut data-auto_prompt na false.

Interfejsy API HTML i JavaScript

W poprzednim przykładzie pokazaliśmy, jak za pomocą nowego interfejsu HTML API dodać logowanie do witryny. Możesz też użyć funkcjonalnie równoważnego interfejsu JavaScript API lub łączyć interfejsy HTML API i JavaScript API na swojej stronie.

Aby interaktywnie wyświetlić opcje dostosowywania przycisków, takie jak typ wywołania zwrotnego i atrybuty, np. kolor, rozmiar, kształt, tekst i motyw, skorzystaj z naszego generatora kodu. Możesz go używać do szybkiego porównywania różnych opcji i generowania fragmentów kodu HTML do wykorzystania w witrynie.

Logowanie jednym dotknięciem z dowolnej strony

Logowanie jednym dotknięciem to nowy, prosty sposób rejestracji i logowania w Twojej witrynie. Umożliwia ona logowanie się użytkowników bezpośrednio z dowolnej strony w Twojej witrynie i eliminuje konieczność odwiedzania przez nich specjalnej strony logowania. Innymi słowy, zmniejsza to trudności związane z rejestracją i logowaniem, ponieważ użytkownicy mogą rejestrować się i logować na stronach innych niż strona logowania.

Aby umożliwić logowanie z dowolnej strony, zalecamy umieszczenie tagu g_id_onload we wspólnym nagłówku, stopce lub innym obiekcie, który jest uwzględniony w całej witrynie.

Zalecamy też dodawanie elementu g_id_signin, który wyświetla spersonalizowany przycisk logowania, tylko na stronach logowania lub zarządzania kontem użytkownika. Daj użytkownikom możliwość wyboru sposobu rejestracji lub logowania, wyświetlając przycisk obok innych przycisków dostawców tożsamości federacyjnej oraz pól do wpisywania nazwy użytkownika i hasła.

Odpowiedź tokena

Logowanie użytkownika nie wymaga już zrozumienia ani używania kodów autoryzacji OAuth 2.0, tokenów dostępu ani tokenów odświeżania. Zamiast tego do udostępniania stanu logowania i profilu użytkownika używany jest token identyfikacyjny tokena internetowego JSON (JWT). Aby jeszcze bardziej uprościć ten proces, nie musisz już używać metod dostępu w stylu „getter” do pracy z danymi profilu użytkownika.

Zwracane są bezpieczne dane logowania w postaci tokena identyfikacyjnego JWT podpisanego przez Google:

• do obsługi wywołania zwrotnego JavaScript w przeglądarce użytkownika w trybie wyskakującego okienka;
• do serwera backendu przez przekierowanie Google do punktu końcowego logowania, gdy przycisk Zaloguj się przez Google ux_mode jest ustawiony na redirect.

W obu przypadkach zaktualizuj istniejące moduły obsługi wywołań zwrotnych, usuwając:

• połączenia na numer googleUser.getBasicProfile(),
• odwołania do BasicProfile i powiązane wywołania metod getId(), getName(), getGivenName(), getFamilyName(), getImageUrl() i getEmail(),
• użycie obiektu AuthResponse.

Zamiast tego używaj bezpośrednich odwołań do credentialpól podrzędnych w nowym obiekcie JWTCredentialResponse, aby pracować z danymi profilu użytkownika.

Dodatkowo, tylko w przypadku trybu przekierowania, zapobiegaj fałszowaniu żądań z innej witryny (CSRF) i weryfikuj token identyfikatora Google na serwerze backendu.

Aby lepiej zrozumieć, jak użytkownicy wchodzą w interakcję z Twoją witryną, możesz użyć pola select_by w obiekcie CredentialResponse, aby określić wynik zgody użytkownika i użyty konkretny proces logowania.

Zgoda użytkownika i cofanie uprawnień

Gdy użytkownik po raz pierwszy loguje się w Twojej witrynie, Google prosi go o zgodę na udostępnienie profilu konta Twojej aplikacji. Dopiero po wyrażeniu zgody profil użytkownika jest udostępniany Twojej aplikacji w ładunku danych uwierzytelniających tokena identyfikatora. Odebranie dostępu do tego profilu jest równoznaczne z odebraniem tokena dostępu w starszej bibliotece logowania.

Użytkownicy mogą cofnąć uprawnienia i odłączyć aplikację od swojego konta Google, otwierając stronę https://myaccount.google.com/permissions. Mogą też rozłączyć się bezpośrednio z aplikacją, wywołując zaimplementowane przez Ciebie wywołanie interfejsu API. Wcześniejsza metoda disconnect została zastąpiona nowszą metodą revoke.

Gdy użytkownik usunie swoje konto na Twojej platformie, zalecamy użycie revoke, aby odłączyć aplikację od jego konta Google.

Wcześniej funkcja auth2.signOut() mogła być używana do zarządzania wylogowywaniem użytkowników z aplikacji. Należy usunąć wszelkie przypadki użycia funkcji auth2.signOut(), a aplikacja powinna bezpośrednio zarządzać stanem sesji poszczególnych użytkowników i stanem logowania.

Stan sesji i słuchacze

Nowa biblioteka nie zachowuje stanu zalogowania ani stanu sesji w przypadku aplikacji internetowej.

Stan zalogowania na konto Google oraz stan sesji i stan zalogowania w aplikacji to odrębne pojęcia.

Stan zalogowania użytkownika na konto Google i w aplikacji jest od siebie niezależny, z wyjątkiem momentu logowania, gdy wiesz, że użytkownik został uwierzytelniony i zalogował się na swoje konto Google.

Jeśli na Twojej stronie są dostępne funkcje Zaloguj się przez Google, Logowanie jednym dotknięciem lub Logowanie automatyczne, użytkownicy muszą najpierw zalogować się na swoje konto Google, aby:

• wyrazić zgodę na udostępnianie swojego profilu użytkownika podczas pierwszej rejestracji lub logowania w Twojej witrynie,
• a później do logowania podczas kolejnych wizyt w witrynie.

Użytkownicy mogą pozostawać zalogowani, wylogowywać się lub przełączać na inne konto Google przy zachowaniu aktywnej sesji logowania w Twojej witrynie.

Od teraz musisz bezpośrednio zarządzać stanem zalogowania użytkowników aplikacji internetowej. Wcześniej Logowanie przez Google pomagało w monitorowaniu stanu sesji użytkownika.

Usuń wszelkie odwołania do auth2.attachClickHandler() i zarejestrowanych w nim procedur obsługi wywołań zwrotnych.

Wcześniej do udostępniania zmian stanu zalogowania na konto Google użytkownika używano odbiorców. Odbiorniki nie są już obsługiwane.

Usuń wszelkie odniesienia do listen(), auth2.currentUser i auth2.isSignedIn.

Pliki cookie

Funkcja Zaloguj się przez Google w ograniczonym zakresie korzysta z plików cookie. Poniżej znajdziesz ich opis. Więcej informacji o innych rodzajach plików cookie używanych przez Google znajdziesz w artykule Jak Google używa plików cookie.

G_ENABLED_IDPSPliki cookie ustawiane przez starszą bibliotekę platformy logowania przez Google nie są już używane.

Nowa biblioteka Google Identity Services może opcjonalnie ustawiać te pliki cookie w różnych domenach na podstawie opcji konfiguracji:

• g_state przechowuje stan wylogowania użytkownika i jest ustawiany podczas korzystania z wyskakującego okienka Jedno dotknięcie lub logowania automatycznego,

• g_csrf_token to plik cookie z podwójnym przesyłaniem, który służy do zapobiegania atakom CSRF i jest ustawiany, gdy wywoływany jest punkt końcowy logowania. Wartość identyfikatora URI logowania może być ustawiona jawnie lub domyślnie może być to identyfikator URI bieżącej strony. Punkt końcowy logowania może być wywoływany w tych warunkach podczas korzystania z:

  • interfejs HTML API z parametrem data-ux_mode=redirect lub gdy ustawiony jest parametr data-login_uri, lub

  • JavaScript API z parametrem ux_mode=redirect, w którym parametr google.accounts.id.prompt() nie jest używany do wyświetlania logowania jednym dotknięciem ani logowania automatycznego.

Jeśli masz usługę, która zarządza plikami cookie, po zakończeniu migracji dodaj 2 nowe pliki cookie i usuń wcześniejszy plik.

Jeśli zarządzasz wieloma domenami lub subdomenami, w artykule Wyświetlanie funkcji logowania jednym kliknięciem w subdomenach znajdziesz dalsze instrukcje dotyczące pracy z plikami cookie g_state.

Dokumentacja migracji obiektów na potrzeby logowania użytkowników