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",
}

Obsługa automatycznego łączenia (pobieranie intencji)

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 zwraca token dla użytkownika. Jeśli konto Google nie jest zgodne z istniejącym użytkownikiem, punkt końcowy wymiany tokenów zwraca błąd linking_error i opcjonalny login_hint.

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=get&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 get.
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.
scope Opcjonalnie: wszystkie zakresy skonfigurowane przez Google pod kątem żądań użytkowników.
client_id Identyfikator klienta przypisany do Google.
client_secret Tajny klucz klienta przypisany do Google.

Aby odpowiedzieć na żądania dotyczące intencji get, 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 użytkownik znajdzie konto, wygeneruj token dostępu i zwróć wartości w obiekcie JSON w treści odpowiedzi HTTPS, tak jak w tym przykładzie:

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

  "expires_in": SECONDS_TO_EXPIRATION
}

W niektórych przypadkach może się zdarzyć, że połączenie kont na podstawie tokena tożsamości stanie się niemożliwe. Jeśli tak jest, Twój punkt końcowy wymiany tokenów musi odpowiedzieć z błędem HTTP 401, który określa error=linking_error, jak pokazano w poniższym przykładzie:

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

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

Gdy Google otrzyma odpowiedź z komunikatem o błędzie 401 z parametrem linking_error, wyśle użytkownika do Twojego punktu końcowego autoryzacji z parametrem login_hint. Użytkownik kończy łączenie kont, korzystając z połączenia OAuth w przeglądarce.

Obsługa tworzenia konta przez Logowanie przez Google (tworzenie intencji)

Gdy użytkownik musi utworzyć konto w usłudze, Google wysyła żądanie do punktu końcowego wymiany tokenów, w którym określono intent=create.

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

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

Punkt końcowy wymiany tokenów musi obsługiwać następujące parametry:

Parametry punktu końcowego tokena
intent W przypadku tych żądań wartość tego parametru wynosi create.
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.

Token JWT w parametrze assertion zawiera identyfikator konta Google użytkownika, jego nazwę oraz adres e-mail, których możesz użyć do utworzenia nowego konta w usłudze.

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

  • Zweryfikuj i odkoduj potwierdzenie tokena JWT.
  • Zweryfikuj informacje o użytkownikach i utwórz nowe konto.
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.

Zweryfikuj informacje o użytkownikach i utwórz nowe konto

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 którykolwiek z tych warunków jest spełniony, poproś użytkownika o połączenie istniejącego konta z kontem Google. Aby to zrobić, odpowiedz na żądanie, podając błąd HTTP 401, który określa error=linking_error, i podaj adres e-mail użytkownika jako login_hint. Oto przykładowa odpowiedź:

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

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

Gdy Google otrzyma odpowiedź z komunikatem o błędzie 401 z parametrem linking_error, wyśle użytkownika do Twojego punktu końcowego autoryzacji z parametrem login_hint. Użytkownik kończy łączenie kont, korzystając z połączenia OAuth w przeglądarce.

Jeśli żaden z tych warunków nie jest spełniony, utwórz nowe konto użytkownika z informacjami podanymi w tokenie JWT. Nowe konta zazwyczaj nie mają skonfigurowanego hasła. Zaleca się dodanie Logowania przez Google na innych platformach, aby umożliwić użytkownikom logowanie się przez Google na wszystkich platformach aplikacji. Możesz też wysłać użytkownikowi e-maila z linkiem, który rozpoczyna proces odzyskiwania hasła, aby umożliwić mu ustawienie hasła na innych platformach.

Po utworzeniu utwórz token dostępu , a następnie zwróć wartości w obiekcie JSON w treści odpowiedzi HTTPS, na przykład:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_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ę.