Migracja z logowania przez Google

Ten przewodnik pomoże Ci zrozumieć niezbędne zmiany i przeprowadzić migrację bibliotek JavaScript ze starszej biblioteki platformy logowania Google do nowszej biblioteki usług tożsamości Google na potrzeby uwierzytelniania.

Jeśli Twój klient używa Biblioteki klienta API Google dla JavaScriptu lub innych starszych bibliotek do autoryzacji, zobacz Migracja do usług tożsamości Google, aby dowiedzieć się więcej.

Uwierzytelnianie i autoryzacja

Uwierzytelnianie określa, kim jest dana osoba, i jest często określany jako rejestracja lub logowanie użytkownika. Autoryzacja to proces przyznawania albo odrzucania dostępu do danych lub zasobów. Na przykład aplikacja prosi użytkownika o zgodę na dostęp do jego Dysku Google.

Tak jak w przypadku starszej biblioteki platformy logowania Google, nowa biblioteka usług tożsamości Google została opracowana z myślą o obsłudze uwierzytelniania i autoryzacji.

Nowsza biblioteka rozdziela te 2 procesy, aby ułatwić programistom integrację kont Google z Twoją aplikacją.

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

Jeśli Twój przypadek użycia obejmuje autoryzację, przeczytaj artykuły Jak działa autoryzacja użytkowników i Migracja do usług tożsamości Google, aby upewnić się, że aplikacja używa nowych, udoskonalonych interfejsów API.

Co się zmieniło?

Użytkownicy mogą korzystać z nowej biblioteki usług Google Identity, która ułatwia korzystanie z nich. Najważniejsze punkty programu:

• nowe, proste w obsłudze funkcje logowania jednym dotknięciem i automatycznym logowaniem, które wymagają mniejszej liczby kroków;
• odświeżony przycisk logowania z możliwością personalizacji,
• spójne marki i jednolite zasady logowania się w internecie zwiększają zrozumienie i zaufanie,
• Użytkownicy mogą szybko i łatwo się zalogować oraz zalogować z dowolnego miejsca w witrynie, bez konieczności logowania się na konto lub do strony konta.

Naszym celem było zmniejszenie złożoności, zwiększenie bezpieczeństwa oraz (np. w najkrótszym czasie) integracja. np.:

• Opcja dodania funkcji logowania się użytkowników do zawartości statycznej witryny tylko za pomocą kodu HTML,
• oddzielenie uwierzytelniania logowania od autoryzacji i udostępnianie danych użytkowników, złożoność integracji OAuth2 nie jest już potrzebna tylko do logowania użytkowników w witrynie.
• Zarówno tryb wyskakującego okienka, jak i tryb przekierowania są nadal obsługiwane, ale infrastruktura Google OAuth2 przekierowuje teraz do punktu logowania serwera backendu,
• łączymy funkcje ze starszych bibliotek Google Identity i bibliotek JavaScript Google API w jedną nową bibliotekę,
• w przypadku odpowiedzi logowania możesz zdecydować, czy chcesz użyć propozycji i pośredniego za pomocą funkcji stylu getter, aby uprościć konfigurację.

Przykład migracji logowania

Jeśli przeprowadzasz migrację z dotychczasowego przycisku logowania do Google i chcesz tylko logować użytkowników w swojej witrynie, najprostszą zmianą jest po prostu zmiana na nowy przycisk spersonalizowany. Można to zrobić, zamieniając biblioteki JavaScript i aktualizując bazę kodu poprzez użycie nowego obiektu.

Biblioteki i konfiguracja

Starsza biblioteka platformy logowania Google: apis.google.com/js/platform.js oraz biblioteka klienta interfejsów API Google dla JavaScriptu: gapi.client nie są już wymagane do uwierzytelniania i autoryzacji użytkowników. Zastąpiła je jedna nowa biblioteka JavaScript usług tożsamości Google: accounts.google.com/gsi/client.

Starsze trzy moduły JavaScript: api, client i platform używane do logowania są wczytywane z apis.google.com. Aby zidentyfikować lokalizacje, w których może znaleźć się stara biblioteka, zazwyczaj:

• domyślny przycisk logowania wczytuje apis.google.com/js/platform.js,
• przycisk graficzny wczytuje się apis.google.com/js/api:client.js,
• bezpośrednie korzystanie z gapi.client powoduje wczytanie apis.google.com/js/api.js.

W większości przypadków możesz po prostu nadal korzystać z istniejących danych logowania identyfikatora klienta aplikacji internetowej. W ramach migracji zalecamy przejrzenie zasad OAuth 2.0 i sprawdzenie w konsoli Google API, w razie potrzeby:

• aplikacje testowe i produkcyjne używają oddzielnych projektów i mają własne identyfikatory klientów.
• typ identyfikatora klienta OAuth 2.0 to „Aplikacja internetowa” oraz
• Protokół HTTPS jest używany w przypadku autoryzowanych źródeł JavaScriptu i identyfikatorów URI przekierowania.

Identyfikacja kodu i testowanie

Plik cookie debugowania może pomóc w zlokalizowaniu kodu, którego dotyczy problem, oraz przetestowaniu działania po jego wycofaniu.

W przypadku dużych lub złożonych aplikacji wykrycie całego kodu spowodowanego wycofaniem modułu gapi.auth2 może być trudne. Aby zarejestrować w konsoli obecne użycie, które wkrótce zostanie wycofane, ustaw wartość pliku cookie G_AUTH2_MIGRATION na informational. Opcjonalnie dodaj dwukropek, a następnie parę klucz-wartość, aby zapisać także pamięć sesji. Gdy się zalogujesz i odbierzesz dane logowania, możesz wysłać zebrane logi do backendu do późniejszej analizy. Na przykład informational:showauth2use zapisuje źródło i adres URL w kluczu pamięci sesji o nazwie showauth2use.

Aby zweryfikować działanie aplikacji, gdy moduł gapi.auth2 nie jest już wczytywany, ustaw wartość pliku cookie G_AUTH2_MIGRATION na enforced. Pozwala to przetestować zachowanie po wycofaniu aplikacji przed datą egzekwowania.

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

• enforced Nie wczytuj modułu gapi.auth2.
• informational Loguj użycie wycofanej funkcji w konsoli JS. Zapisz też w pamięci sesji, gdy ustawiona jest opcjonalna nazwa klucza: informational:key-name.

Aby zminimalizować wpływ użytkownika, zalecamy utworzenie pliku cookie lokalnie podczas programowania i testowania, zanim użyjesz go w środowiskach produkcyjnych.

HTML i JavaScript

W tym scenariuszu logowania używanym tylko do uwierzytelniania pokazane są przykładowy kod i renderowanie istniejącego przycisku logowania Google. Wybierz opcję Wyskakujące okienko lub Tryb przekierowania, aby zobaczyć różnice w sposobie obsługi odpowiedzi uwierzytelniania przez wywołanie zwrotne JavaScript lub przez bezpieczne przekierowanie do punktu końcowego logowania serwera backendu.

Stary 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 prostym scenariuszu logowania tylko do uwierzytelniania, wybierz opcję Wyskakujące okienko lub Przekierowanie i użyj przykładowego kodu, aby zastąpić istniejącą 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 prostym przykładzie, który wymaga tylko uwierzytelniania, nowa biblioteka accounts.google.com/gsi/client, klasa g_id_signin i obiekt g_id_onload zastępują starszą bibliotekę apis.google.com/js/platform.js i obiekt g-signin2.

Oprócz wyświetlania nowego spersonalizowanego przycisku przykładowy kod pokazuje też wyskakujące okienko One Tap. Niezależnie od tego, gdzie będziesz wyświetlać spersonalizowany przycisk, zdecydowanie zalecamy, aby wyświetlać także wyskakujące okienko, które pozwoli Ci w prosty sposób obsługiwać użytkowników podczas rejestracji i logowania.

Chociaż nie jest to zalecane ze względu na zwiększone pole logowania, nowy przycisk może być wyświetlany sam, bez jednoczesnego wyświetlania okna dialogowego One Tap. Aby to zrobić, ustaw dla atrybutu data-auto_prompt wartość false.

Interfejsy API związane z HTML i JavaScript

Powyższy przykład pokazuje, jak za pomocą nowego interfejsu HTML API dodać logowanie do witryny. Możesz też użyć w swojej witrynie funkcjonalnego interfejsu API JavaScript lub mieszać i dopasowywać interfejsy API HTML i JavaScript.

Aby skorzystać z interaktywnego widoku opcji dostosowywania przycisków, takich jak typ wywołania zwrotnego i atrybuty, takie jak kolor, rozmiar, kształt, tekst i motyw, skorzystaj z generatora kodu. Można go użyć do szybkiego porównania różnych opcji i wygenerowania fragmentów kodu HTML do wykorzystania w witrynie.

Loguj się na dowolnej stronie jednym kliknięciem

Jedno dotknięcie to nowy, łatwy w obsłudze sposób, który pozwala użytkownikom na rejestrację lub logowanie się na Twojej stronie. Umożliwia ona logowanie się użytkowników bezpośrednio z dowolnej strony w witrynie i eliminuje potrzebę otwierania osobnej strony logowania. Inaczej mówiąc, ułatwia to użytkownikom rejestrację i logowanie się na stronach innych niż strona logowania.

Aby włączyć logowanie z dowolnej strony, zalecamy dodanie elementu g_id_onload do udostępnionego nagłówka, stopki lub innego obiektu występującego w całej witrynie.

Zalecamy również dodanie g_id_signin, który wyświetla spersonalizowany przycisk logowania, tylko na stronach logowania lub zarządzania kontami użytkowników. Daj użytkownikom możliwość rejestracji lub logowania się, wyświetlając ten przycisk obok innych przycisków sfederowanego dostawcy tożsamości oraz pól nazwy użytkownika i hasła.

Odpowiedź tokena

Logowanie użytkowników nie wymaga już zrozumienia lub obsługi kodów autoryzacji OAuth2, tokenów dostępu ani tokenów odświeżania. Zamiast tego tokenu identyfikatora tokena JSON (JWT) używa się do udostępniania stanu logowania i profilu użytkownika. Aby jeszcze bardziej uprościć ten proces, nie musisz już używać metod akcesora pobierającego, aby pracować z danymi profilu użytkownika.

Dane logowania bezpiecznego tokena JWT podpisanego przez Google są zwracane:

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

• połączenia z numerem googleUser.getBasicProfile(),
• odwołania do BasicProfile i powiązanych wywołań metod getId(), getName(), getGivenName(), getFamilyName(), getImageUrl(), getEmail() oraz
• wykorzystania obiektu AuthResponse.

Aby korzystać z danych profilu użytkownika, zamiast tego użyj bezpośrednich odwołań do pól podrzędnych credential w nowym obiekcie JWT CredentialResponse.

Dodatkowo w przypadku trybu przekierowania pamiętaj, aby zapobiec fałszowaniu żądań między witrynami (CSRF) i weryfikowaniu tokena identyfikatora Google na serwerze backendu.

Aby lepiej zrozumieć, jak użytkownicy wchodzą w interakcje z Twoją witryną, możesz użyć pola select_by w polu CredentialResponse do ustalania wyniku zgody użytkownika i wybranego procesu logowania.

Zgoda użytkownika i unieważnianie uprawnień

Gdy użytkownik loguje się w Twojej witrynie po raz pierwszy, Google prosi go o zgodę na udostępnienie profilu konta swojej aplikacji. Po wyrażeniu zgody przez użytkownika profil użytkownika jest udostępniany w aplikacji jako ładunek danych logowania. Unieważnienie dostępu do tego profilu jest równoważne unieważnieniu tokena dostępu w starej bibliotece logowania.

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

Gdy użytkownik usunie swoje konto z Twojej platformy, najlepiej jest użyć revoke, aby odłączyć aplikację od konta Google.

Wcześniej można było używać interfejsu auth2.signOut() do zarządzania wylogowywaniem się użytkowników z aplikacji. Należy przestać używać auth2.signOut() i zarządzać bezpośrednio aplikacjami według stanu sesji użytkownika i stanu logowania.

Stan sesji i odbiorniki

Nowa biblioteka nie zachowuje stanu zalogowania lub stanu sesji aplikacji internetowej.

Stan zalogowania na koncie Google oraz stan sesji i zalogowanie w aplikacji to odrębne kategorie.

Stan logowania się użytkownika na jego koncie Google i w Twojej aplikacji jest niezależny od innych aplikacji. Nie dotyczy to samego momentu logowania, gdy użytkownik wie, że został uwierzytelniony i jest zalogowany na swoje konto Google.

Gdy w Twojej witrynie znajduje się funkcja Zaloguj się przez Google, jednorazowe lub automatyczne logowanie, użytkownicy muszą najpierw zalogować się na swoje konto Google, aby:

• udzielić zgody na udostępnienie profilu użytkownika przy pierwszej rejestracji lub zalogowaniu się w witrynie,
• a później przy logowaniu do witryny.

Użytkownicy mogą pozostać zalogowani i wylogować się na inne konto Google oraz przełączyć się na inne, a w witrynie pozostają aktywne sesje po zalogowaniu.

Odpowiadasz teraz bezpośrednio za zarządzanie stanem zalogowania użytkowników swojej aplikacji internetowej. Wcześniej Logowanie przez Google pomagało w monitorowaniu stanu sesji użytkownika.

Usuń wszystkie odwołania do auth2.attachClickHandler() i zarejestrowanych modułów obsługi wywołań zwrotnych.

Wcześniej detektory służyły do udostępniania informacji o zmianach stanu zalogowania na konto Google użytkownika. Słuchacze nie są już obsługiwani.

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

Pliki cookie

Funkcja Zaloguj się przez Google w ograniczonym stopniu korzysta z plików cookie, więc ich opis znajduje się poniżej. Więcej informacji o innych typach plików cookie używanych przez Google znajdziesz w artykule Jak Google korzysta z plików cookie.

Plik cookie G_ENABLED_IDPS utworzony przez starą bibliotekę biblioteki logowania Google nie jest już używany.

Nowa biblioteka usług tożsamości Google może opcjonalnie ustawić te pliki cookie dla różnych domen zgodnie z opcjami konfiguracji:

• Aplikacja g_state przechowuje informacje o wylogowaniu użytkownika. Jest ona ustawiana, gdy używasz wyskakującego okienka lub logowania automatycznego,

• g_csrf_token to plik cookie przesyłany dwukrotnie, który służy do zapobiegania atakom CSRF i jest ustawiany po wywołaniu punktu końcowego logowania. Identyfikator URI logowania można ustawić wprost lub domyślnie. Punkt końcowy logowania może być wywołany pod tymi warunkami, gdy używasz:

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

  • JavaScript API z ux_mode=redirect i gdzie google.accounts.id.prompt() nie jest używany do wyświetlania One Tap ani automatycznego logowania.

Jeśli masz usługę, która zarządza plikami cookie, pamiętaj, aby dodać dwa nowe pliki cookie i usunąć stary plik po zakończeniu migracji.

Jeśli zarządzasz wieloma domenami lub subdomenami, zobacz artykuł Wyświetlanie jednego kliknięcia w subdomenach, aby uzyskać dalsze instrukcje dotyczące pracy z plikiem cookie g_state.

Dokumentacja migracji obiektów w przypadku logowania użytkownika