Uproszczone łączenie za pomocą protokołu OAuth i Logowania przez Google

Przegląd

Uproszczone łączenie za pomocą Logowania przez Google opartego na OAuth dodaje Logowanie przez Google do łączenia za pomocą OAuth. Zapewnia to użytkownikom Google płynne łączenie kont, a opcjonalnie także tworzenie konta, które umożliwia użytkownikowi utworzenie nowego konta w Twojej usłudze za pomocą konta Google.

Aby połączyć konta za pomocą OAuth i zalogować się przez Google, wykonaj te ogólne czynności:

1. Najpierw poproś użytkownika o zgodę na dostęp do jego profilu Google.
2. Użyj informacji z profilu, aby sprawdzić, czy konto użytkownika istnieje.
3. W przypadku dotychczasowych użytkowników połącz konta.
4. Jeśli nie możesz znaleźć odpowiednika użytkownika Google w swoim systemie uwierzytelniania, zweryfikuj token identyfikatora otrzymany od Google. Jeśli Twoja usługa obsługuje tworzenie kont, możesz utworzyć użytkownika na podstawie informacji o profilu zawartych w tokenie identyfikatora.

Łączenie konta na telefonie użytkownika za pomocą uproszczonego łączenia

Rysunek 1. Łączenie kont na telefonie użytkownika za pomocą uproszczonego łączenia

Uproszczone łączenie: proces OAuth + Logowanie przez Google

Poniższy diagram sekwencji przedstawia interakcje między użytkownikiem, Google i punktem końcowym wymiany tokenów w przypadku uproszczonego łączenia.

Rysunek 2. Sekwencja zdarzeń w procesie uproszczonego łączenia

.

Role i obowiązki

W tabeli poniżej znajdziesz definicje ról i obowiązków podmiotów w procesie uproszczonego łączenia.

Użytkownik, który wykonał czynność / komponent	Rola GAL	Podmiot odpowiedzialny
Aplikacja / serwer Google	Klient OAuth	Uzyskuje zgodę użytkownika na logowanie się za pomocą Google, przekazuje do serwera potwierdzenia tożsamości (JWT) i bezpiecznie przechowuje uzyskane tokeny.
Punkt końcowy wymiany tokenów	Dostawca tożsamości / serwer autoryzacji	Weryfikuje potwierdzenia tożsamości, sprawdza, czy istnieją już konta, obsługuje wymagane intencje połączenia kont (check, get) i opcjonalną intencję create oraz wydaje tokeny na podstawie żądanych intencji.
Interfejs API usługi	Serwer zasobów	Umożliwia dostęp do danych użytkownika po okazaniu prawidłowego tokena dostępu.

Wymagania dotyczące uproszczonego łączenia

• Wdróż proces podstawowego łączenia za pomocą OAuth. Usługa musi obsługiwać zgodne z OAuth 2.0 punkty końcowe autoryzacji i wymiany tokenów.
• Punkt końcowy wymiany tokenów musi obsługiwać asercje tokena sieciowego JSON (JWT) i wdrażać wymagane intencje check i get oraz opcjonalnie intencję create.

Uwaga: te intencje muszą być zaimplementowane w tym samym punkcie końcowym wymiany tokenów, który został utworzony na potrzeby przepływu podstawowego łączenia OAuth. Nie twórz innego punktu końcowego do obsługi tych intencji.

• Zarejestruj identyfikator klienta Google API.

Logika podejmowania decyzji w przypadku uproszczonego łączenia

Oto logika, która określa, jak wywoływane są intencje podczas uproszczonego procesu łączenia:

1. Czy użytkownik ma konto w Twoim systemie uwierzytelniania? (Użytkownik decyduje, wybierając TAK lub NIE)
   1. TAK : czy użytkownik używa adresu e-mail powiązanego z kontem Google do logowania się na Twojej platformie? (Użytkownik decyduje, wybierając TAK lub NIE)
      1. YES : czy użytkownik ma pasujące konto w Twoim systemie uwierzytelniania? (wywoływany jest check zamiar, aby potwierdzić)
         1. TAK : wywoływany jest get intent, a konto jest łączone, jeśli funkcja get intent zwróci prawidłowy wynik.
         2. NIE : Utworzyć nowe konto? (Użytkownik decyduje, wybierając TAK lub NIE; dotyczy tylko usług, które umożliwiają tworzenie kont)
            1. YES : wywoływany jest element create intent, a konto jest połączone, jeśli funkcja create intent zwróci wartość wskazującą powodzenie.
            2. NIE : uruchamiany jest proces łączenia OAuth, użytkownik jest przekierowywany do przeglądarki i ma możliwość połączenia się z innym adresem e-mail.
      2. NIE : uruchamiany jest proces łączenia OAuth, użytkownik jest przekierowywany do przeglądarki i ma możliwość połączenia się z innym adresem e-mail.
   2. NIE : Czy użytkownik ma pasujące konto w Twoim systemie uwierzytelniania? (wywoływany jest check zamiar, aby potwierdzić)
      1. TAK : wywoływana jest get intent, a konto jest łączone, jeśli get intent zwróci wartość.
      2. NIE : jeśli usługa obsługuje tworzenie konta, wywoływany jest createintent, a konto jest łączone, jeśli intent create zwraca wartość powodzenia. Jeśli tworzenie konta nie jest obsługiwane, punkt końcowy powinien zwrócić kod HTTP 401 linking_error, aby wywołać alternatywny proces łączenia OAuth.

Przepis na wdrożenie

Punkt końcowy wymiany tokenów musi obsługiwać wymagane intencje check i get oraz opcjonalnie intencję create, aby obsługiwać uproszczone łączenie.

Aby obsłużyć różne intencje, wykonaj te czynności:

Sprawdzanie, czy użytkownik ma już konto (intencja check)

Google wywołuje Twój punkt końcowy wymiany tokenów, aby sprawdzić, czy użytkownik Google istnieje w Twoim systemie. Szczegóły parametrów znajdziesz w sekcji Uproszczone intencje łączenia.

Przepis na implementację

Aby obsłużyć wymaganą intencję check, wykonaj te czynności:

1. Sprawdź poprawność żądania:

   • Sprawdź client_id, client_secret i grant_type (musi to być urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Sprawdź assertion (JWT) zgodnie z kryteriami opisanymi w sekcji Weryfikacja JWT.

2. Wyszukaj użytkownika:

   • Sprawdź, czy identyfikator konta Google (sub) lub adres e-mail w tokenie JWT pasuje do użytkownika w Twojej bazie danych.

3. Odpowiedz:

   • Jeśli użytkownik zostanie znaleziony: zwróć kod HTTP 200 OK z wartością {"account_found": "true"}.
   • Jeśli nie znaleziono: zwróć kod HTTP 404 Not Found z {"account_found": "false"}.

Handle automatic linking (get intent)

If the account exists, Google calls your endpoint with intent=get to retrieve tokens. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the required get intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Lookup user:

   • Verify the user exists using the sub or email claim.

3. Respond:

   • If successful: Generate and return access_token, refresh_token, and expires_in in a JSON response (HTTP 200 OK).
   • If linking fails: Return HTTP 401 Unauthorized with {"error": "linking_error"} and an optional login_hint to fall back to standard OAuth linking.

Handle account creation using Sign in with Google (create intent)

Note: Supporting the create intent is optional. The required intents for Streamlined Linking are check and get.

If your service supports account creation and no account exists, Google calls your endpoint with intent=create to create a new user. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the optional create intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Verify user does not exist:

   • Check if the sub or email is already in your database.
   • If the user does exist: Return HTTP 401 Unauthorized with {"error": "linking_error", "login_hint": "USER_EMAIL"} to force fallback to OAuth linking.

3. Create account:

   • Use the sub, email, name, and picture claims from the JWT to create a new user record.

4. Respond:

   • Generate and return tokens in a JSON response (HTTP 200 OK).

Uzyskiwanie identyfikatora klienta Google API

Podczas procesu rejestracji łączenia konta musisz podać identyfikator klienta interfejsu Google API. Aby uzyskać identyfikator klienta interfejsu API, użyj projektu utworzonego podczas wykonywania czynności związanych z łączeniem OAuth. Aby to zrobić, wykonaj te czynności:

1. Otwórz stronę Klienci.

2. Utwórz lub wybierz projekt interfejsów API Google.

   Jeśli w projekcie nie ma identyfikatora klienta dla typu aplikacji internetowej, kliknij Utwórz klienta, aby go utworzyć. W polu Autoryzowane źródła JavaScriptu podaj domenę swojej witryny. Podczas przeprowadzania testów lokalnych lub tworzenia aplikacji musisz dodać zarówno http://localhost, jak i http://localhost:<port_number> do pola Autoryzowane źródła JavaScript.

   Ważna uwaga: w przypadku testów lokalnych lub prac programistycznych dodaj zarówno http://localhost, jak i http://localhost:<port_number> do pola Autoryzowane źródła JavaScript.

   Uwaga: identyfikator klienta wygląda tak jak w tym przykładzie:

   1234567890-abc123def456.apps.googleusercontent.com
   

Sprawdzanie poprawności implementacji

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.