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.
Weryfikowanie i dekodowanie potwierdzenia JWT

Potwierdzenie JWT możesz zweryfikować i zdekodować za pomocą Biblioteka dekodowania JWT dla Twojego języka Używaj Klucze publiczne Google, dostępne w tych krajach: JWK lub formaty PEM do weryfikacji, podpis tokena.

Po zdekodowaniu potwierdzenie JWT wygląda jak w tym 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 wydawca (pole iss) to https://accounts.google.com, oznacza to, że odbiorcy (pole aud) to przypisany identyfikator klienta, który nie wygasł. (pole exp).

Za pomocą pól email, email_verified i hd możesz określić, Google hostuje dany adres e-mail i jest dla niego autorytatywny. W przypadku, gdy Google autorytatywny, według którego użytkownik jest obecnie znany jako rzeczywisty właściciel konta i możesz pominąć hasło i inne testy zabezpieczające. W przeciwnym razie te metody mogą zostać użyte do zweryfikowania konta przed połączeniem.

Przypadki, w których Google ma wiarygodność:

  • To jest konto Gmail, adres email ma sufiks @gmail.com.
  • To jest konto G Suite, email_verified ma wartość prawda i ustawiono hd.

Użytkownicy mogą rejestrować się w Google, nie korzystając z Gmaila lub G Suite. Kiedy email nie zawiera sufiksu @gmail.com, a hd nie występuje w Google zalecamy wiarygodność i hasło lub inne metody weryfikujące weryfikację użytkownika. email_verified może również być prawdziwe, ponieważ wstępnie zweryfikowaliśmy, że użytkownika przy tworzeniu konta Google, jednak własność firmy zewnętrznej konto e-mail mogło się od tego czasu zmienić.

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.
Weryfikowanie i dekodowanie potwierdzenia JWT

Potwierdzenie JWT możesz zweryfikować i zdekodować za pomocą Biblioteka dekodowania JWT dla Twojego języka Używaj Klucze publiczne Google, dostępne w tych krajach: JWK lub formaty PEM do weryfikacji, podpis tokena.

Po zdekodowaniu potwierdzenie JWT wygląda jak w tym 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 wydawca (pole iss) to https://accounts.google.com, oznacza to, że odbiorcy (pole aud) to przypisany identyfikator klienta, który nie wygasł. (pole exp).

Za pomocą pól email, email_verified i hd możesz określić, Google hostuje dany adres e-mail i jest dla niego autorytatywny. W przypadku, gdy Google autorytatywny, według którego użytkownik jest obecnie znany jako rzeczywisty właściciel konta i możesz pominąć hasło i inne testy zabezpieczające. W przeciwnym razie te metody mogą zostać użyte do zweryfikowania konta przed połączeniem.

Przypadki, w których Google ma wiarygodność:

  • To jest konto Gmail, adres email ma sufiks @gmail.com.
  • To jest konto G Suite, email_verified ma wartość prawda i ustawiono hd.

Użytkownicy mogą rejestrować się w Google, nie korzystając z Gmaila lub G Suite. Kiedy email nie zawiera sufiksu @gmail.com, a hd nie występuje w Google zalecamy wiarygodność i hasło lub inne metody weryfikujące weryfikację użytkownika. email_verified może również być prawdziwe, ponieważ wstępnie zweryfikowaliśmy, że użytkownika przy tworzeniu konta Google, jednak własność firmy zewnętrznej konto e-mail mogło się od tego czasu zmienić.

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.
Weryfikowanie i dekodowanie potwierdzenia JWT

Potwierdzenie JWT możesz zweryfikować i zdekodować za pomocą Biblioteka dekodowania JWT dla Twojego języka Używaj Klucze publiczne Google, dostępne w tych krajach: JWK lub formaty PEM do weryfikacji, podpis tokena.

Po zdekodowaniu potwierdzenie JWT wygląda jak w tym 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 wydawca (pole iss) to https://accounts.google.com, oznacza to, że odbiorcy (pole aud) to przypisany identyfikator klienta, który nie wygasł. (pole exp).

Za pomocą pól email, email_verified i hd możesz określić, Google hostuje dany adres e-mail i jest dla niego autorytatywny. W przypadku, gdy Google autorytatywny, według którego użytkownik jest obecnie znany jako rzeczywisty właściciel konta i możesz pominąć hasło i inne testy zabezpieczające. W przeciwnym razie te metody mogą zostać użyte do zweryfikowania konta przed połączeniem.

Przypadki, w których Google ma wiarygodność:

  • To jest konto Gmail, adres email ma sufiks @gmail.com.
  • To jest konto G Suite, email_verified ma wartość prawda i ustawiono hd.

Użytkownicy mogą rejestrować się w Google, nie korzystając z Gmaila lub G Suite. Kiedy email nie zawiera sufiksu @gmail.com, a hd nie występuje w Google zalecamy wiarygodność i hasło lub inne metody weryfikujące weryfikację użytkownika. email_verified może również być prawdziwe, ponieważ wstępnie zweryfikowaliśmy, że użytkownika przy tworzeniu konta Google, jednak własność firmy zewnętrznej konto e-mail mogło się od tego czasu zmienić.

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ę.