Uproszczenie łączenia przy użyciu OAuth i Logowania przez Google

Przegląd

Oparte na protokole OAuth łączenie z użyciem protokołu OAuth dodaje funkcję Logowanie przez OAuth. Ułatwia to użytkownikom łączenie się z Google, a także umożliwia tworzenie kont, które pozwalają użytkownikom tworzyć nowe konta w usłudze za pomocą konta Google.

Aby połączyć konto przez OAuth i logowanie przez Google, wykonaj te ogólne czynności:

  1. Najpierw poproś użytkownika o zgodę na dostęp do jego profilu Google.
  2. Sprawdź w profilu, czy konto użytkownika istnieje.
  3. Jeśli jesteś już użytkownikiem, połącz konta.
  4. Jeśli nie możesz znaleźć dopasowania użytkownika Google do swojego systemu uwierzytelniania, sprawdź token tożsamości otrzymany od Google. Następnie możesz utworzyć konto użytkownika na podstawie informacji o profilu zawartych w tokenie identyfikatora.
Ilustracja przedstawiająca kroki, jakie musi wykonać użytkownik, aby połączyć swoje konto Google przy użyciu uproszczonego procesu łączenia. Pierwszy zrzut ekranu pokazuje, jak użytkownik może wybrać Twoją aplikację do połączenia. Drugi zrzut ekranu pozwala użytkownikowi sprawdzić, czy ma już konto w usłudze. Trzeci zrzut ekranu pozwala użytkownikowi wybrać konto Google, które chce połączyć. Czwarty zrzut ekranu przedstawia potwierdzenie połączenia konta Google z aplikacją. Piąty zrzut ekranu przedstawia połączone konto użytkownika w aplikacji Google.

Rysunek 1. Łączenie kont na telefonie użytkownika dzięki uproszczonemu łączeniu

Wymagania dotyczące płynnego łączenia

Implementowanie serwera OAuth

Punkt końcowy tokena giełdy musi obsługiwać intencje check, create i get. Poniżej znajdziesz instrukcje wykonane podczas łączenia kont oraz wskazówki dotyczące wywołania różnych intencji:

  1. Czy użytkownik ma konto w systemie uwierzytelniania? (Użytkownik decyduje o treści TAK lub NIE)
    1. TAK : Czy użytkownik używa adresu e-mail powiązanego z kontem Google, by logować się na Twojej platformie? (Użytkownik decyduje o treści TAK lub NIE)
      1. TAK : Czy użytkownik ma pasujące konto w systemie uwierzytelniania? (check intent zawiera prośbę o potwierdzenie)
        1. TAK : narzędzie get intent jest wywoływane, a konto jest połączone, jeśli intencja zwróci się.
        2. NIE : utworzyć nowe konto? (Użytkownik decyduje o treści TAK lub NIE)
          1. TAK: narzędzie create intent jest wywoływane, a konto jest połączone, jeśli intencja skutecznie zwróci intencję.
          2. NIE : użytkownik uruchomi proces protokołu OAuth, użytkownik zostanie przekierowany do przeglądarki, a użytkownik będzie mógł połączyć się z innym adresem e-mail.
      2. NIE : użytkownik wywołał proces Web OAuth, użytkownik został przekierowany do przeglądarki, a użytkownik mógł połączyć się z innym adresem e-mail.
    2. NIE : Czy użytkownik ma pasujące konto w systemie uwierzytelniania? (check intent zawiera prośbę o potwierdzenie)
      1. TAK : narzędzie get intent jest wywoływane, a konto jest połączone, jeśli intencja zwróci się.
      2. NIE : wywoływany jest element create intent, a konto jest połączone, jeśli intencja utworzenia się uda.

Sprawdzanie, czy konto użytkownika już istnieje (sprawdź intencję)

Gdy użytkownik wyrazi zgodę na dostęp do jego profilu Google, Google wyśle żądanie zawierające podpisane potwierdzenie tożsamości użytkownika Google. Potwierdzenie zawiera informacje, które obejmują identyfikator konta Google, nazwę użytkownika oraz adres e-mail użytkownika. Punkt końcowy wymiany tokenów skonfigurowany dla Twojego projektu obsługuje to żądanie.

Jeśli odpowiednie konto Google jest już obecne w Twoim systemie uwierzytelniania, punkt końcowy wymiany tokenów zawiera odpowiedź account_found=true. Jeśli konto Google nie jest zgodne z istniejącym użytkownikiem, punkt końcowy wymiany tokenów zwraca błąd HTTP 404 (nie znaleziono strony) w account_found=false.

Prośba ma następującą postać:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

Punkt końcowy wymiany tokenów musi mieć możliwość obsługi następujących parametrów:

Parametry punktu końcowego tokena
intent W przypadku tych żądań wartość tego parametru wynosi check.
grant_type Typ wymienianego tokena. W przypadku tych żądań ten parametr ma wartość urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion Token internetowy JSON (JWT) zapewniający podpisane potwierdzenie tożsamości użytkownika Google. Token JWT zawiera informacje takie jak identyfikator konta Google, nazwa użytkownika i adres e-mail użytkownika.
client_id Identyfikator klienta przypisany do Google.
client_secret Tajny klucz klienta przypisany do Google.

Aby odpowiedzieć na żądania dotyczące intencji check, Twój punkt końcowy wymiany tokenów musi wykonać te czynności:

  • Zweryfikuj i odkoduj potwierdzenie tokena JWT.
  • Sprawdź, czy konto Google znajduje się już w Twoim systemie uwierzytelniania.
Sprawdź poprawność i zdekoduj asercję JWT

Potwierdzenie JWT można sprawdzić i zdekodować, używając biblioteki dekodującej JWT dla swojego języka . Użyj kluczy publicznych Google, dostępnych w formatach JWK lub PEM , aby zweryfikować podpis tokena.

Po zdekodowaniu asercja JWT wygląda jak w następującym przykładzie:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Oprócz weryfikacji podpisu tokena sprawdź, czy wystawca potwierdzenia (pole iss ) to https://accounts.google.com , czy odbiorca (pole aud ) to przypisany przez Ciebie identyfikator klienta oraz czy token nie wygasł ( exp pole).

Korzystając z pól email , email_verified i hd możesz określić, czy Google obsługuje adres e-mail i czy jest miarodajny. W przypadkach, gdy Google jest autorytatywnym użytkownikiem, wiadomo, że użytkownik jest prawowitym właścicielem konta i możesz pominąć hasło lub inne metody sprawdzania. W przeciwnym razie te metody mogą służyć do weryfikacji konta przed połączeniem.

Przypadki, w których Google jest autorytatywny:

  • email ma przyrostek @gmail.com , to jest konto Gmail.
  • email_verified ma wartość true i ustawiono hd , to jest konto G Suite.

Użytkownicy mogą rejestrować się na konta Google bez korzystania z Gmaila ani G Suite. Jeśli email nie zawiera sufiksu @gmail.com i nie ma hd Google nie jest autorytatywny i zaleca się podanie hasła lub innych metod sprawdzania tożsamości w celu zweryfikowania użytkownika. email_verfied może również mieć wartość true, ponieważ firma Google wstępnie zweryfikowała użytkownika podczas tworzenia konta Google, jednak własność konta e-mail innej firmy mogła ulec zmianie od tego czasu.

Sprawdź, czy konto Google znajduje się już w Twoim systemie uwierzytelniania

Sprawdź, czy spełniony jest jeden z tych warunków:

  • Identyfikator konta Google, który znajduje się w polu sub potwierdzenia, znajduje się w Twojej bazie danych użytkowników.
  • Adres e-mail w potwierdzeniu znajduje się w bazie danych użytkownika.

Jeśli spełniony jest dowolny z tych warunków, użytkownik już się zarejestrował. W takim przypadku zwróć odpowiedź w ten sposób:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

Jeśli identyfikator konta Google ani adres e-mail podany w potwierdzeniu nie pasują do użytkownika w Twojej bazie danych, nie jest on jeszcze zarejestrowany. W tym przypadku Twój punkt końcowy wymiany tokenów musi odpowiadać z błędem HTTP 404, który określa "account_found": "false", jak w tym przykładzie:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

Handle automatic linking (get intent)

After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.

If the corresponding Google Account is already present in your authentication system, your token exchange endpoint returns a token for the user. If the Google Account doesn't match an existing user, your token exchange endpoint returns a linking_error error and optional login_hint.

The request has the following form:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

Your token exchange endpoint must be able to handle the following parameters:

Token endpoint parameters
intent For these requests, the value of this parameter is get.
grant_type The type of token being exchanged. For these requests, this parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
scope Optional: Any scopes that you've configured Google to request from users.
client_id The client ID you assigned to Google.
client_secret The client secret you assigned to Google.

To respond to the get intent requests, your token exchange endpoint must perform the following steps:

  • Validate and decode the JWT assertion.
  • Check if the Google account is already present in your authentication system.
Sprawdź poprawność i zdekoduj asercję JWT

Potwierdzenie JWT można sprawdzić i zdekodować, używając biblioteki dekodującej JWT dla swojego języka . Użyj kluczy publicznych Google, dostępnych w formatach JWK lub PEM , aby zweryfikować podpis tokena.

Po zdekodowaniu asercja JWT wygląda jak w następującym przykładzie:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Oprócz weryfikacji podpisu tokena sprawdź, czy wystawca potwierdzenia (pole iss ) to https://accounts.google.com , czy odbiorca (pole aud ) to przypisany przez Ciebie identyfikator klienta oraz czy token nie wygasł ( exp pole).

Korzystając z pól email , email_verified i hd możesz określić, czy Google obsługuje adres e-mail i czy jest miarodajny. W przypadkach, gdy Google jest autorytatywnym użytkownikiem, wiadomo, że użytkownik jest prawowitym właścicielem konta i możesz pominąć hasło lub inne metody sprawdzania. W przeciwnym razie te metody mogą służyć do weryfikacji konta przed połączeniem.

Przypadki, w których Google jest autorytatywny:

  • email ma przyrostek @gmail.com , to jest konto Gmail.
  • email_verified ma wartość true i ustawiono hd , to jest konto G Suite.

Użytkownicy mogą rejestrować się na konta Google bez korzystania z Gmaila ani G Suite. Jeśli email nie zawiera sufiksu @gmail.com i nie ma hd Google nie jest autorytatywny i zaleca się podanie hasła lub innych metod sprawdzania tożsamości w celu zweryfikowania użytkownika. email_verfied może również mieć wartość true, ponieważ firma Google wstępnie zweryfikowała użytkownika podczas tworzenia konta Google, jednak własność konta e-mail innej firmy mogła ulec zmianie od tego czasu.

Check if the Google account is already present in your authentication system

Check whether either of the following conditions are true:

  • The Google Account ID, found in the assertion's sub field, is in your user database.
  • The email address in the assertion matches a user in your user database.

If an account is found for the user, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

In some cases, account linking based on ID token might fail for the user. If it does so for any reason, your token exchange endpoint needs to reply with a HTTP 401 error that specifies error=linking_error, as the following example shows:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

When Google receives a 401 error response with linking_error, Google sends the user to your authorization endpoint with login_hint as a parameter. The user completes account linking using the OAuth linking flow in their browser.

Handle account creation via Google Sign-In (create intent)

When a user needs to create an account on your service, Google makes a request to your token exchange endpoint that specifies intent=create.

The request has the following form:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

Your token exchange endpoint must able to handle the following parameters:

Token endpoint parameters
intent For these requests, the value of this parameter is create.
grant_type The type of token being exchanged. For these requests, this parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
client_id The client ID you assigned to Google.
client_secret The client secret you assigned to Google.

The JWT within the assertion parameter contains the user's Google Account ID, name, and email address, which you can use to create a new account on your service.

To respond to the create intent requests, your token exchange endpoint must perform the following steps:

  • Validate and decode the JWT assertion.
  • Validate user information and create new account.
Sprawdź poprawność i zdekoduj asercję JWT

Potwierdzenie JWT można sprawdzić i zdekodować, używając biblioteki dekodującej JWT dla swojego języka . Użyj kluczy publicznych Google, dostępnych w formatach JWK lub PEM , aby zweryfikować podpis tokena.

Po zdekodowaniu asercja JWT wygląda jak w następującym przykładzie:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Oprócz weryfikacji podpisu tokena sprawdź, czy wystawca potwierdzenia (pole iss ) to https://accounts.google.com , czy odbiorca (pole aud ) to przypisany przez Ciebie identyfikator klienta oraz czy token nie wygasł ( exp pole).

Korzystając z pól email , email_verified i hd możesz określić, czy Google obsługuje adres e-mail i czy jest miarodajny. W przypadkach, gdy Google jest autorytatywnym użytkownikiem, wiadomo, że użytkownik jest prawowitym właścicielem konta i możesz pominąć hasło lub inne metody sprawdzania. W przeciwnym razie te metody mogą służyć do weryfikacji konta przed połączeniem.

Przypadki, w których Google jest autorytatywny:

  • email ma przyrostek @gmail.com , to jest konto Gmail.
  • email_verified ma wartość true i ustawiono hd , to jest konto G Suite.

Użytkownicy mogą rejestrować się na konta Google bez korzystania z Gmaila ani G Suite. Jeśli email nie zawiera sufiksu @gmail.com i nie ma hd Google nie jest autorytatywny i zaleca się podanie hasła lub innych metod sprawdzania tożsamości w celu zweryfikowania użytkownika. email_verfied może również mieć wartość true, ponieważ firma Google wstępnie zweryfikowała użytkownika podczas tworzenia konta Google, jednak własność konta e-mail innej firmy mogła ulec zmianie od tego czasu.

Validate user information and create new account

Check whether either of the following conditions are true:

  • The Google Account ID, found in the assertion's sub field, is in your user database.
  • The email address in the assertion matches a user in your user database.

If either condition is true, prompt the user to link their existing account with their Google Account. To do so, respond to the request with an HTTP 401 error that specifies error=linking_error and gives the user's email address as the login_hint. The following is a sample response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

When Google receives a 401 error response with linking_error, Google sends the user to your authorization endpoint with login_hint as a parameter. The user completes account linking using the OAuth linking flow in their browser.

If neither condition is true, create a new user account with the information provided in the JWT. New accounts don't typically have a password set. It's recommended that you add Google Sign-In to other platforms to enable users to log in with Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password to sign in on other platforms.

When the creation is completed, issue an access token and refresh token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

Uzyskiwanie identyfikatora klienta Google API

Podczas rejestracji konta musisz podać identyfikator klienta Google API.

Aby uzyskać identyfikator klienta API, użyj projektu utworzonego podczas wykonywania kroków łączenia OAuth. Aby to zrobić:

  1. Otwórz stronę Dane logowania w konsoli interfejsu API Google.
  2. Utwórz lub wybierz projekt interfejsów API Google.

    Jeśli Twój projekt nie ma identyfikatora klienta dla typu aplikacji internetowej, kliknij Utwórz dane logowania i identyfikator klienta OAuth, by go utworzyć. Pamiętaj, aby w polu Autoryzowane źródła JavaScript umieścić domenę swojej witryny. Podczas wykonywania testów lokalnych lub programowania należy dodać zarówno pole http://localhost, jak i http://localhost:<port_number> w polu Autoryzowane źródła JavaScript.

Sprawdzanie poprawności implementacji

Można sprawdzić poprawność implementacji za pomocą OAuth 2.0 Playground narzędzia.

W narzędziu wykonaj następujące czynności:

  1. Kliknij konfiguracji , aby otworzyć okno konfiguracji OAuth 2.0.
  2. W dziedzinie przepływu OAuth, wybierz Client-side.
  3. W polu OAuth Endpoints wybierz Niestandardowy.
  4. W odpowiednich polach określ punkt końcowy OAuth 2.0 i identyfikator klienta przypisany do Google.
  5. W sekcji Krok 1, nie zaznaczaj żadnych zakresów Google. Zamiast tego pozostaw to pole puste lub wpisz zakres poprawny dla Twojego serwera (lub dowolny ciąg, jeśli nie używasz zakresów OAuth). Kiedy skończysz, kliknij autoryzacji API.
  6. W etapie 2 i etapem 3 części, przechodzą przepływu OAuth 2.0 i upewnić się, że każdy etap działa zgodnie z zamierzeniem.

Można sprawdzić poprawność implementacji za pomocą konta Google Linking Demo narzędzia.

W narzędziu wykonaj następujące czynności:

  1. Kliknij Sign-in z przycisku Google.
  2. Wybierz konto, które chcesz połączyć.
  3. Wprowadź identyfikator usługi.
  4. Opcjonalnie wprowadź co najmniej jeden zakres, do którego poprosisz o dostęp.
  5. Kliknij Start Demo.
  6. Po wyświetleniu monitu potwierdź, że możesz wyrazić zgodę i odrzucić prośbę o połączenie.
  7. Potwierdź, że zostałeś przekierowany na swoją platformę.