Migracja z logowania przez Google

Ten przewodnik pomoże Ci zrozumieć niezbędne zmiany i czynności, które należy wykonać, aby przenieść biblioteki JavaScript z wcześniejszej biblioteki platformy Google Sign-In do nowszej biblioteki Google Identity Services w celu uwierzytelniania.

Jeśli Twój klient korzysta z biblioteki klienta interfejsu API Google dla JavaScriptu lub innej wcześniejszej biblioteki do autoryzacji, zapoznaj się z artykułem Przejście na usługi Google Identity.

Uwierzytelnianie i autoryzacja

Uwierzytelnianie służy do ustalania tożsamości użytkownika i jest powszechnie nazywane rejestracją lub logowaniem użytkownika. Autoryzacja to proces przyznawania lub odmowy przyznania dostępu do danych lub zasobów. Na przykład aplikacja prosi o zgodę użytkownika na dostęp do jego Dysku Google.

Podobnie jak wcześniejsza biblioteka platformy Google Sign-In nowa biblioteka Google Identity Services została zaprojektowana tak, aby obsługiwać zarówno procesy uwierzytelniania, jak i autoryzacji.

Nowsza biblioteka oddziela jednak te 2 procesy, aby ułatwić deweloperom integrację kont Google z aplikacją.

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

Jeśli Twój przypadek użycia obejmuje autoryzację, zapoznaj się z artykułami Jak działa autoryzacja użytkownika i Przejście na usługi tożsamości Google, aby upewnić się, że Twoja aplikacja korzysta z nowych, ulepszonych interfejsów API.

Co się zmieniło

Nowa biblioteka Google Identity Services oferuje użytkownikom wiele ulepszeń w zakresie użyteczności. Najważniejsze informacje:

• nowe procesy logowania automatycznego i jednym dotknięciem o mniejszej liczbie kroków,
• odświeżony przycisk logowania z personalizacją użytkownika,
• spójny wizerunek marki i jednolite zachowanie podczas logowania się w internecie, które zwiększają zaufanie i zrozumienie,
• szybki dostęp do treści; użytkownicy mogą rejestrować się i logować w dowolnym miejscu w witrynie bez konieczności otwierania strony logowania lub konta.

W przypadku deweloperów skupiliśmy się na zmniejszeniu złożoności, poprawie bezpieczeństwa i jak najszybszym przeprowadzeniu integracji. Wśród tych ulepszeń znajdują się:

• opcja logowania się użytkowników do treści statycznych witryny za pomocą samego kodu HTML,
• rozdzielenie uwierzytelniania podczas logowania od autoryzacji i udostępniania danych użytkownika, dzięki czemu złożoność integracji OAuth 2.0 nie jest już potrzebna do logowania użytkowników na stronie,
• nadal obsługiwane są oba tryby: wyskakujące okienko i przekierowanie, ale infrastruktura OAuth 2.0 Google przekierowuje teraz do punktu logowania serwera zaplecza.
• konsolidacja funkcji z wcześniejszych bibliotek Google Identity i Google API JavaScript w jednej nowej bibliotece,
• dla odpowiedzi związanych z logowaniem możesz teraz zdecydować, czy chcesz użyć funkcji Promise i pośrednio za pomocą funkcji stylu pobierania, aby uprościć sobie działanie.

Przykład migracji logowania

Jeśli przechodzisz z obecnego przycisku Logowanie przez Google i interesuje Cię tylko logowanie użytkowników w witrynie, najprostszą zmianą będzie przełączenie się na nowy spersonalizowany przycisk. Aby to zrobić, wymień biblioteki JavaScript i zaktualizuj kod źródłowy, aby używać nowego obiektu logowania.

Biblioteki i konfiguracja

Wcześniejsza biblioteka platformy logowania przez Google (apis.google.com/js/platform.js) oraz biblioteka klienta interfejsów API Google do języka JavaScript: gapi.client nie są już wymagane do uwierzytelniania i autoryzacji użytkowników. Zastąpiliśmy je jedną nową biblioteką JavaScript usług tożsamości Google: accounts.google.com/gsi/client.

Trzy wcześniejsze moduły JavaScript: api, client i platform używane do logowania są ładowane z apis.google.com. Aby ułatwić Ci identyfikowanie miejsc, w których starsza biblioteka może być uwzględniona w Twojej witrynie, zwykle:

• wczytuje się domyślny przycisk logowania apis.google.com/js/platform.js,
• wczytuje się grafika niestandardowego przycisku apis.google.com/js/api:client.js,
• bezpośrednie wykorzystanie gapi.client ładuje apis.google.com/js/api.js.

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

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

Identyfikowanie kodu i testowanie

Cookie debugowania może pomóc w znalezieniu kodu, którego dotyczy wycofanie, oraz przetestowaniu jego działania po wycofaniu.

W dużych lub złożonych aplikacjach znalezienie całego kodu, którego dotyczy wycofanie modułu gapi.auth2, może być trudne. Aby rejestrować w konsoli obecne wykorzystanie funkcji, które wkrótce zostaną wycofane, ustaw wartość pliku cookie G_AUTH2_MIGRATION na informational. Opcjonalnie możesz dodać dwukropek i wartość klucza, aby prowadzić też logowanie w magazynie sesji. Po zalogowaniu się i otrzymaniu danych logowania możesz sprawdzić zebrane logi lub wysłać je do backendu w celu późniejszej analizy. Na przykład informational:showauth2use zapisuje źródło i adres URL w kluczu pamięci sesji o nazwie showauth2use.

Aby sprawdzić zachowanie aplikacji, gdy moduł gapi.auth2 nie jest już wczytywany, ustaw wartość pliku cookie G_AUTH2_MIGRATION na enforced. Umożliwia to przetestowanie zachowania po wycofaniu przed datą wprowadzenia.

Możliwe wartości pliku cookie G_AUTH2_MIGRATION:

• enforced Nie wczytuj modułu gapi.auth2.
• informational Zaloguj w konsoli JS użycie przestarzałych funkcji. Loguj się też do pamięci sesji po ustawieniu opcjonalnej nazwy klucza: informational:key-name.

Aby zminimalizować wpływ na użytkowników, zalecamy najpierw ustawienie tego pliku cookie lokalnie podczas tworzenia i testowania, a dopiero potem użycie go w środowiskach produkcyjnych.

HTML i JavaScript

W tym scenariuszu logowania się tylko do uwierzytelniania pokazano przykładowy kod i renderowanie dotychczasowego przycisku logowania w Google. Wybierz tryb wyskakującego okienka lub przekierowania, aby zobaczyć różnice w sposobie obsługi odpowiedzi uwierzytelniającej przez wywołanie zwrotne JavaScriptu lub bezpieczne przekierowanie do punktu końcowego logowania na serwerze zaplecza.

Wcześniej

<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żywać nowej biblioteki w sytuacji logowania tylko do uwierzytelniania, wybierz tryb wyskakującego okienka lub przekierowania i zastąp obecną implementację na stronie logowania za pomocą przykładowego kodu.

<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śniejsze bibliotekę apis.google.com/js/platform.js i obiekt g-signin2.

Oprócz renderowania nowego przycisku z personalizacją przykładowy kod wyświetla też nowe wyskakujące okienko One Tap. Zalecamy, aby wszędzie tam, gdzie wyświetlasz przycisk personalizowany, wyświetlać też wyskakujące okienko One Tap, 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 wyświetlania okna 1 dotknięcia. Aby to zrobić, ustaw atrybut data-auto_prompt na false.

Interfejsy HTML i JavaScript API

Poprzedni przykład pokazuje, jak korzystać z nowego interfejsu HTML API w celu dodania opcji logowania do witryny. Możesz też użyć funkcjonalnego odpowiednika JavaScript API lub połączyć i dopasować interfejsy API HTML i JavaScript w całej witrynie.

Aby interaktywnie wyświetlić opcje dostosowywania przycisku, takie jak typ wywołania zwrotnego i atrybuty, takie jak 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 użycia w witrynie.

Logowanie się jednym dotknięciem z dowolnej strony

Rejestracja i logowanie jednym dotknięciem to nowy sposób na łatwe rejestrowanie się i logowanie w Twojej witrynie. Umożliwia ona logowanie się użytkowników bezpośrednio z dowolnej strony w witrynie i eliminuje konieczność otwierania przez nich specjalnej strony logowania. Innymi słowy, ta funkcja zmniejsza trudności związane z rejestracją i logowaniem się, ponieważ daje użytkownikom możliwość rejestracji i logowania się z innych stron niż strona logowania.

Aby umożliwić logowanie się z dowolnej strony, zalecamy umieszczenie elementu g_id_onload w wspólnym nagłówku, stopce lub innym obiekcie w całej witrynie.

Zalecamy też dodanie g_id_signin, który wyświetla przycisk spersonalizowanego logowania, tylko na stronach logowania lub zarządzania kontami użytkowników. Daj użytkownikom możliwość wyboru sposobu rejestracji lub logowania, wyświetlając przycisk obok innych przycisków dostawców tożsamości i pól na nazwę użytkownika i hasło.

Odpowiedź tokena

Logowanie użytkownika nie wymaga już znajomości kodów autoryzacji, tokenów dostępu ani tokenów odświeżania OAuth 2.0. Zamiast tego do udostępniania stanu logowania i profilu użytkownika używa się tokena ID sieciowego JSON (JWT). Dzięki temu nie musisz już używać metod dostępu w stylu „getter” do pracy z danymi profilu użytkownika.

Dane logowania w postaci podpisanego przez Google tokena JWT z identyfikatorem tożsamości są zwracane w jednym z tych formatów:

• do modułu obsługi wywołań zwrotnych JavaScript w przeglądarce w trybie wyskakującego okienka,
• na serwer 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łania zwrotnego, usuwając:

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

Zamiast tego użyj bezpośrednich odwołań do pól podrzędnych credential w nowym obiekcie JWT CredentialResponse, aby pracować z danymi profilu użytkownika.

Dodatkowo tylko w przypadku trybu przekierowania pamiętaj, aby zapobiegać fałszowaniu żądań między witrynami (CSRF) i weryfikować token identyfikatora Google na serwerze zaplecza.

Aby lepiej zrozumieć, jak użytkownicy korzystają z Twojej witryny, możesz użyć pola select_by w danych CredentialResponse, aby określić wynik zgody użytkownika i użyty proces logowania.

Zgoda użytkownika i unieważnianie uprawnień

Gdy użytkownik po raz pierwszy loguje się na Twojej stronie internetowej, 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 tokenie ID z danymi uwierzytelniania. Odebranie dostępu do tego profilu jest równoznaczne z odebraniem tokena dostępu w bibliotece z wcześniejszym logowaniem.

Użytkownicy mogą cofnąć uprawnienia i odłączyć Twoją aplikację od konta Google, odwiedzając stronę https://myaccount.google.com/permissions. Mogą też odłączyć się bezpośrednio od aplikacji, wywołując wywołanie interfejsu API, które wdrożysz. Wcześniejsza metoda disconnect została zastąpiona nowszą metodą revoke.

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

Wcześniej auth2.signOut() można było używać do zarządzania wylogowywaniem użytkowników z aplikacji. Należy usunąć wszelkie użycia auth2.signOut(), a aplikacja powinna bezpośrednio zarządzać stanem sesji i stanem logowania użytkowników.

Stan sesji i słuchacze

Nowa biblioteka nie zachowuje stanu logowania ani stanu sesji w aplikacji internetowej.

Stan zalogowania na konto Google oraz stan sesji i stan zalogowania w aplikacji to 2 różne pojęcia.

Stan logowania użytkownika na jego koncie Google i w aplikacji są od siebie niezależne, z wyjątkiem momentu logowania, gdy wiadomo, że użytkownik się uwierzytelnił i jest zalogowany na swoje konto Google.

Jeśli na stronie włączone są opcje 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ępnienie profilu użytkownika podczas rejestracji lub logowania się w Twojej witrynie,
• i później podczas logowania się w Twojej witrynie.

Użytkownicy mogą pozostać zalogowani, wylogować się lub przełączyć na inne konto Google, zachowując aktywną sesję w Twojej witrynie.

Teraz odpowiadasz za bezpośrednie zarządzanie stanem zalogowania użytkowników swojej aplikacji internetowej. Wcześniej funkcja Logowanie przez Google umożliwiała monitorowanie stanu sesji użytkownika.

Usuń wszystkie odwołania do auth2.attachClickHandler() i zarejestrowanych przez nią obsługiwanych wywołań zwrotnych.

Wcześniej Listenery były używane do udostępniania zmian w stanie zalogowania na konto Google użytkownika. Detektory nie są już obsługiwane.

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

Pliki cookie

Logowanie przez Google używa ograniczonej liczby plików cookie. Poniżej znajdziesz ich opis. Więcej informacji o innych typach plików cookie używanych przez Google znajdziesz w artykule Jak Google używa plików cookie.

Plik cookie G_ENABLED_IDPS ustawiony przez wcześniejszą bibliotekę Google Sign-In Platform nie jest już używany.

Nowa biblioteka usług tożsamości Google może opcjonalnie ustawiać te pliki cookie między domenami na podstawie opcji konfiguracji:

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

• g_csrf_token to plik cookie służący do podwójnego przesyłania, który zapobiega atakom CSRF. Jest ustawiany, gdy wywoływany jest punkt końcowy logowania. Wartość identyfikatora URI logowania można ustawić bezpośrednio lub może być domyślnie ustawiona jako identyfikator URI bieżącej strony. Punkt końcowy logowania może być wywoływany w tych warunkach, jeśli używany jest:

  • HTML API z wartością data-ux_mode=redirect lub data-login_uri,

  • Interfejs JavaScript API z ux_mode=redirect, w którym 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, dodaj 2 nowe pliki cookie i usuń starszy plik cookie po zakończeniu migracji.

Jeśli zarządzasz wieloma domenami lub subdomenami, przeczytaj artykuł Wyświetlanie jednym kliknięciem w subdomenach, aby dowiedzieć się, jak korzystać z pliku cookie g_state.

Dokumentacja migracji obiektów związanej z logowaniem się użytkowników