Łączenie kont z łączeniem Logowania przez Google opartym na protokole OAuth

Ujednolicone połączenie typu Logowanie przez Google oparte na protokole OAuth powoduje dodanie Logowania przez Google zamiast łączenia kont przez OAuth. Użytkownicy Google będą mogli bezproblemowo korzystać z połączeń głosowych, a jednocześnie umożliwić łączenie kont użytkownikom, którzy zarejestrowali się w Twojej usłudze przy użyciu tożsamości innej niż Google.

Ten typ połączenia zaczyna się od Logowania przez Google, który umożliwia sprawdzenie, czy informacje o profilu Google użytkownika istnieją w Twoim systemie. Jeśli dane użytkownika nie zostaną znalezione w systemie, rozpocznie się standardowy przepływ OAuth. Użytkownik może również utworzyć nowe konto z użyciem swoich informacji z profilu Google.

Rysunek 1. Gdy akcja uzyska dostęp do profilu Google użytkownika, możesz go użyć, aby znaleźć użytkownika w swoim systemie uwierzytelniania.

Aby przeprowadzić łączenie kont w ramach uproszczonych połączeń, wykonaj te ogólne czynności:

  1. Najpierw poproś użytkownika o zgodę na dostęp do jego profilu Google.
  2. Użyć informacji z profilu do zidentyfikowania użytkownika.
  3. Jeśli nie możesz znaleźć w swoim systemie uwierzytelniania pasującego do użytkownika Google, proces przebiega w zależności od tego, czy w Konsoli Actions skonfigurowano projekt Actions, aby umożliwiać tworzenie kont użytkowników za pomocą poleceń głosowych czy tylko w witrynie.
    • Jeśli zezwalasz na tworzenie konta za pomocą głosu, zweryfikuj token identyfikatora otrzymany od Google. Następnie możesz utworzyć użytkownika na podstawie informacji o profilu zawartych w tokenie identyfikatora.
    • Jeśli nie zezwolisz na tworzenie kont za pomocą głosu, użytkownik zostanie przeniesiony do przeglądarki, w której może wczytać stronę autoryzacji i dokończyć proces tworzenia konta.
Jeśli zezwalasz na głosowe tworzenie kont i nie możesz znaleźć dopasowania do profilu Google w swoim systemie uwierzytelniania, musisz zweryfikować token identyfikatora otrzymany od Google. Następnie możesz utworzyć użytkownika na podstawie informacji o profilu zawartych w tokenie identyfikatora. Jeśli nie zezwolisz na tworzenie kont użytkowników za pomocą głosu, użytkownik zostanie przeniesiony do przeglądarki, w której może wczytać stronę autoryzacji i dokończyć ten proces.
Rysunek 2. Wizualna reprezentacja procesu OAuth i logowania przez Google, gdy w systemie nie znaleziono danych użytkownika.

Pomoc przy tworzeniu konta za pomocą głosu

Jeśli zezwolisz na tworzenie kont użytkowników za pomocą poleceń głosowych, Asystent zapyta użytkownika, czy chce:

  • utworzyć nowe konto w systemie, korzystając z informacji o koncie Google użytkownika lub
  • Jeśli użytkownik ma konto inne niż Google, zaloguj się do systemu uwierzytelniania, korzystając z innego konta.

Zezwolenie na tworzenie kont za pomocą poleceń głosowych jest zalecane, jeśli chcesz uprościć proces tworzenia konta. Użytkownik musi opuścić proces głosowy tylko wtedy, gdy chce zalogować się, korzystając z dotychczasowego konta innego niż konto Google.

Nie zezwalaj na tworzenie kont za pomocą głosu

Jeśli nie zezwolisz na tworzenie kont użytkowników za pomocą poleceń głosowych, Asystent otworzy adres URL witryny podanej przez Ciebie na potrzeby uwierzytelniania użytkownika. Jeśli interakcja odbywa się na urządzeniu bez ekranu, Asystent kieruje użytkownika do telefonu, na którym można kontynuować proces łączenia kont.

Niedozwolone jest tworzenie treści, jeśli:

  • nie chcesz zezwalać użytkownikom, którzy mają konta inne niż Google, na tworzenie nowych kont i łączenie ich z dotychczasowymi kontami w systemie uwierzytelniania. Jeśli na przykład oferujesz program lojalnościowy, warto upewnić się, że użytkownik nie straci punktów zgromadzonych na jego istniejącym koncie.

  • Musisz mieć pełną kontrolę nad procesem tworzenia konta. Możesz na przykład uniemożliwić tworzenie konta, jeśli musisz pokazać użytkownikowi warunki korzystania z usługi podczas tworzenia konta.

Implementowanie uproszczonego połączenia logowania przez Google opartego na protokole OAuth

Konta są połączone ze standardowymi procesami OAuth 2.0. Actions on Google obsługuje przepływy kodu niejawnego i autoryzacyjnego.

W pośrednim przepływie kodu Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Po udanym logowaniu zwracasz token dostępu o długim czasie do Google. Ten token dostępu jest teraz dołączany do każdego żądania wysyłanego przez Asystenta do działania.

W ramach procesu kodu autoryzacji potrzebujesz 2 punktów końcowych:

  • Punkt końcowy autoryzacji, który odpowiada za wyświetlanie interfejsu logowania użytkownikom, którzy nie są jeszcze zalogowani, i rejestrowanie zgody w żądanym terminie w postaci kodu o ograniczonym czasie ważności.
  • Punkt końcowy giełdy tokenów odpowiedzialny za 2 typy giełd:
    1. Wymienia kod autoryzacji tokena długoterminowego i tokena dostępu o ograniczonym czasie ważności. Ta wymiana ma miejsce, gdy użytkownik przechodzi przez proces łączenia kont.
    2. Wymienia długotrwały token odświeżania na token dostępu o ograniczonym czasie ważności. Ta giełda ma miejsce, gdy Google potrzebuje nowego tokena dostępu, ponieważ wygasł.

Implementacja niejawnego przepływu kodu jest prostsza, ale Google zaleca, aby tokeny dostępu wydane z wykorzystaniem niejawnego przepływu nigdy nie wygasały, ponieważ korzystanie z tożsamości w wyniku takiego działania wymusza na użytkowniku ponowne połączenie konta. Jeśli ze względów bezpieczeństwa zależy Ci na wygaśnięciu tokena, rozważ użycie kodu uwierzytelniania.

Konfigurowanie projektu

Aby skonfigurować w projekcie uproszczone łączenie, wykonaj te czynności:

  1. Otwórz Konsolę Actions i wybierz projekt, którego chcesz użyć.
  2. Kliknij kartę Programowanie i wybierz Łączenie kont.
  3. Kliknij przełącznik obok opcji Łączenie kont.
  4. W sekcji Tworzenie konta wybierz Tak.

  5. W sekcji Typ połączenia wybierz Logowanie przez OAuth i Google oraz Pośredni.

  6. W sekcji Informacje o kliencie wykonaj te czynności:

    • Przypisz wartość do Identyfikatora klienta wydanego przez Actions to Google, aby identyfikować żądania pochodzące od Google.
    • Wstaw adresy URL punktów końcowych autoryzacji i Token Exchange.

  7. Kliknij Zapisz.

Wdrażanie serwera OAuth

Aby obsługiwać przepływ niejawny OAuth 2.0, Twoja usługa udostępnia punkt końcowy autoryzacji za pomocą protokołu HTTPS. Ten punkt końcowy odpowiada za uwierzytelnianie i uzyskiwanie od użytkowników zgody na dostęp do danych. Punkt końcowy autoryzacji wyświetla interfejs logowania użytkownikom, którzy nie są jeszcze zalogowani, i zapisuje zgodę na przyznanie dostępu.

Gdy akcja musi wywołać jeden z autoryzowanych interfejsów API Twojej usługi, Google używa tego punktu końcowego, aby uzyskać od użytkowników uprawnienia do wywoływania tych interfejsów API w ich imieniu.

Typowa sesja przepływu niejawnego OAuth 2.0 zainicjowana przez Google ma taki przepływ:

  1. Google otworzy punkt końcowy autoryzacji w przeglądarce użytkownika. Użytkownik loguje się, jeśli jeszcze nie jest zalogowany, i przyznaje Google uprawnienia dostępu do swoich danych za pomocą Twojego interfejsu API, jeśli jeszcze tego nie zrobił.
  2. Usługa tworzy token dostępu i zwraca go do Google, przekierowując przeglądarkę użytkownika z powrotem do Google z tokenem dostępu dołączonym do żądania.
  3. Google wywołuje interfejsy API Twojej usługi i do każdego żądania dołącza token dostępu. Twoja usługa sprawdza, czy token dostępu przyznaje Google autoryzację dostępu do interfejsu API, a następnie wykonuje wywołanie interfejsu API.

Obsługa żądań autoryzacji

Gdy akcja musi przeprowadzić łączenie kont z wykorzystaniem przepływu niejawnego OAuth 2.0, Google wysyła użytkownika do punktu końcowego autoryzacji z żądaniem zawierającym te parametry:

Parametry punktu końcowego autoryzacji
client_id Identyfikator klienta przypisany przez Ciebie do Google.
redirect_uri Adres URL, na który wysyłasz odpowiedź na to żądanie.
state Wartość księgowa, która jest zwracana do Google bez zmian w identyfikatorze URI przekierowania.
response_type Typ wartości do zwrócenia w odpowiedzi. W przypadku przepływu niejawnego OAuth 2.0 typ odpowiedzi to zawsze token.

Jeśli na przykład punkt końcowy autoryzacji jest dostępny pod adresem https://myservice.example.com/auth, żądanie może wyglądać tak:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

Aby punkt końcowy autoryzacji obsługiwał żądania logowania, wykonaj te czynności:

  1. Sprawdź wartości client_id i redirect_uri, aby zapobiec przyznaniu dostępu do niezamierzonych lub błędnie skonfigurowanych aplikacji klienckich:

    • Sprawdź, czy client_id jest zgodny z identyfikatorem klienta przypisanym przez Ciebie do Google.
    • Sprawdź, czy adres URL określony przez parametr redirect_uri ma taki format: 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      YOUR_PROJECT_ID to identyfikator znajdujący się na stronie Ustawienia projektu w Konsoli Actions.

  2. Sprawdź, czy użytkownik jest zalogowany w Twojej usłudze. Jeśli użytkownik nie jest zalogowany, dokończ proces logowania lub rejestracji w usłudze.

  3. Wygeneruj token dostępu, którego Google będzie używać do uzyskiwania dostępu do Twojego interfejsu API. Token dostępu może być dowolną wartością ciągu znaków, ale musi w unikalny sposób reprezentować użytkownika oraz klienta, dla którego jest przeznaczony. Token nie może dać się odgadnąć.

  4. Wyślij odpowiedź HTTP, która przekierowuje przeglądarkę użytkownika pod adres URL określony w parametrze redirect_uri. We fragmencie adresu URL uwzględnij wszystkie te parametry:

    • access_token: wygenerowany przed chwilą token dostępu;
    • token_type: ciąg znaków bearer.
    • state: niezmodyfikowana wartość stanu z pierwotnego żądania. Oto przykład wynikowego adresu URL:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Moduł obsługi przekierowań OAuth 2.0 Google otrzyma token dostępu i sprawdzi, czy wartość state się nie zmieniła. Gdy Google uzyska token dostępu do Twojej usługi, będzie dołączać go do kolejnych wywołań akcji w ramach żądania AppRequest.

Obsługa automatycznego łączenia

Gdy użytkownik wyrazi zgodę na dostęp przez akcję 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 użytkownika, imię i nazwisko oraz adres e-mail. Punkt końcowy giełdy tokenów skonfigurowany dla projektu obsługuje to żądanie.

Jeśli w Twoim systemie uwierzytelniania znajduje się już odpowiednie konto Google, punkt końcowy tokena Exchange zwraca token użytkownika. Jeśli konto Google nie pasuje do istniejącego użytkownika, punkt końcowy tokena wymiany tokenów zwraca błąd user_not_found.

Prośba ma taką 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&consent_code=CONSENT_CODE&scope=SCOPES

Punkt końcowy tokena wymiany musi obsługiwać te parametry:

Parametry punktu końcowego tokena
grant_type Typ wymienianego tokena. W przypadku tych żądań parametr ma wartość urn:ietf:params:oauth:grant-type:jwt-bearer.
intent W przypadku tych żądań wartość tego parametru to „get”.
assertion Token internetowy JSON (JWT) zawierający podpisane potwierdzenie tożsamości użytkownika Google. Token JWT zawiera informacje obejmujące identyfikator konta Google, imię i nazwisko oraz adres e-mail użytkownika.
consent_code Opcjonalnie: jeśli występuje, jednorazowy kod wskazujący, że użytkownik wyraził zgodę na dostęp do określonych zakresów przez akcję.
scope Opcjonalnie: wszelkie zakresy skonfigurowane przez Google, aby żądać od użytkowników.

Gdy punkt końcowy wymiany tokenów otrzyma żądanie połączenia, powinien wykonać te czynności:

Weryfikowanie i dekodowanie potwierdzenia JWT

Możesz zweryfikować i zdekodować potwierdzenie JWT za pomocą biblioteki dekodowania JWT w swoim języku. Sprawdź podpis tokena za pomocą kluczy publicznych Google (dostępnych w formacie JWK lub PEM).

Po zdekodowaniu potwierdzenie JWT wygląda tak:

{
  "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
  "locale": "en_US"
}

Oprócz weryfikacji podpisu tokena sprawdź, czy wydawca potwierdzenia (pole iss) to https://accounts.google.com, a grupa odbiorców (pole aud) to identyfikator klienta przypisany do akcji.

Sprawdź, czy konto Google nie występuje już w Twoim systemie uwierzytelniania

Sprawdź, czy spełniony jest któryś 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 jest zgodny z adresem w bazie danych użytkowników.

Jeśli dowolny z tych warunków jest spełniony, użytkownik już się zarejestrował, więc możesz wystawić token dostępu.

Jeśli identyfikator konta Google ani adres e-mail określony w potwierdzeniu nie pasują do użytkownika w Twojej bazie danych, oznacza to, że jeszcze się nie zarejestrował. W tym przypadku punkt końcowy tokena wymiany tokenów powinien wysłać odpowiedź z komunikatem o błędzie HTTP 401, który określa error=user_not_found, jak w tym przykładzie:

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

{
  "error":"user_not_found",
}
Gdy Google otrzyma odpowiedź o błędzie 401 z błędem user_not_found, wywołuje punkt końcowy wymiany tokenów z wartością parametru intent ustawionego na create i wysyła w żądaniu token identyfikatora, który zawiera informacje o profilu użytkownika.

Obsługa tworzenia konta za pomocą Logowania przez Google

Gdy użytkownik musi utworzyć konto w Twojej usłudze, Google wysyła żądanie do punktu końcowego tokena wymiany tokenów, który określa intent=create, jak w tym przykładzie:

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&consent_code=CONSENT_CODE&assertion=JWT[&NEW_ACCOUNT_INFO]

Parametr assertion zawiera token sieciowy JSON (JWT), który stanowi podpisane potwierdzenie tożsamości użytkownika Google. Token JWT zawiera informacje obejmujące identyfikator konta Google, imię i nazwisko oraz adres e-mail użytkownika, których możesz użyć do utworzenia nowego konta w swojej usłudze.

Aby odpowiadać na żądania utworzenia konta, punkt końcowy tokena wymiany musi wykonywać te czynności:

Weryfikowanie i dekodowanie potwierdzenia JWT

Możesz zweryfikować i zdekodować potwierdzenie JWT za pomocą biblioteki dekodowania JWT w swoim języku. Sprawdź podpis tokena za pomocą kluczy publicznych Google (dostępnych w formacie JWK lub PEM).

Po zdekodowaniu potwierdzenie JWT wygląda tak:

{
  "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
  "locale": "en_US"
}

Oprócz weryfikacji podpisu tokena sprawdź, czy wydawca potwierdzenia (pole iss) to https://accounts.google.com, a grupa odbiorców (pole aud) to identyfikator klienta przypisany do akcji.

Sprawdź poprawność informacji o użytkowniku i utwórz nowe konto

Sprawdź, czy spełniony jest któryś 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 jest zgodny z adresem w bazie danych użytkowników.

Jeśli którykolwiek z warunków jest spełniony, poproś użytkownika o połączenie istniejącego konta z kontem Google, odpowiadając na żądanie z komunikatem błędu HTTP 401, podając adres error=linking_error i adres e-mail użytkownika jako login_hint, jak w tym przykładzie:

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

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

Jeśli żaden z tych warunków nie jest spełniony, utwórz nowe konto użytkownika na podstawie informacji podanych w tokenie JWT. Nowe konta zwykle nie mają ustawionego hasła. Zalecamy dodanie Logowania przez Google na innych platformach, aby umożliwić użytkownikom logowanie się przez Google w różnych miejscach w aplikacji. Możesz też wysłać użytkownikowi e-maila z linkiem rozpoczynającym proces odzyskiwania hasła, który umożliwi mu ustawienie hasła umożliwiającego logowanie się na innych platformach.

Po zakończeniu tworzenia wygeneruj token dostępu i zwróć wartości w obiekcie JSON w treści odpowiedzi HTTPS, jak w tym przykładzie: 

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  
  "expires_in": SECONDS_TO_EXPIRATION
}

Zaprojektuj interfejs głosowy pod kątem przepływu uwierzytelniania

Sprawdź, czy użytkownik został zweryfikowany, i rozpocznij proces łączenia kont

  1. Otwórz projekt Actions Builder w Konsoli Actions.
  2. Utwórz nową scenę, aby rozpocząć łączenie kont w Akcji:
    1. Kliknij Sceny.
    2. Aby dodać nową scenę, kliknij ikonę dodaj (+).
  3. W nowo utworzonej scenie kliknij ikonę dodawania w sekcji Warunki.
  4. Dodaj warunek, który będzie sprawdzał, czy użytkownik powiązany z rozmową jest użytkownikiem zweryfikowanym. Jeśli sprawdzanie się nie powiedzie, akcja nie będzie mogła łączyć kont w trakcie rozmowy i powinna przyznać dostęp do funkcji, które nie wymagają łączenia kont.
    1. W polu Enter new expression w sekcji Warunek wpisz tę funkcję: user.verificationStatus != "VERIFIED"
    2. W sekcji Przejście wybierz scenę, która nie wymaga łączenia kont, ani scenę, która stanowi punkt wejścia do funkcji tylko dla gości.

  1. Kliknij ikonę dodawania obok pozycji Warunki.
  2. Dodaj warunek aktywujący proces łączenia kont, jeśli użytkownik nie ma powiązanej tożsamości.
    1. W polu Enter new expression w sekcji Warunek wpisz tę funkcję: user.verificationStatus == "VERIFIED"
    2. W sekcji Przenoszenie wybierz scenę systemową Łączenie kont.
    3. Kliknij Zapisz.

Po zapisaniu do projektu zostanie dodana nowa scena systemu łączenia kont o nazwie <SceneName>_AccountLinking.

Dostosowywanie sceny łączenia kont

  1. W sekcji Sceny wybierz scenę systemową łączenia kont.
  2. Kliknij Wyślij prośbę i dodaj krótkie zdanie opisujące użytkownikowi, dlaczego akcja musi uzyskać dostęp do jego tożsamości (np. „Aby zapisać Twoje ustawienia”).
  3. Kliknij Zapisz.

  1. W sekcji Warunki kliknij Jeśli użytkownik ukończy łączenie kont.
  2. Skonfiguruj sposób postępowania, jeśli użytkownik zgodzi się na połączenie swojego konta. Możesz na przykład wywołać webhooka, aby przetworzyć dowolną niezbędną niestandardową logikę biznesową i przejść z powrotem do sceny źródłowej.
  3. Kliknij Zapisz.

  1. W sekcji Warunki kliknij Jeśli użytkownik anuluje lub odrzuci łączenie kont.
  2. Skonfiguruj sposób postępowania, jeśli użytkownik nie zgadza się na połączenie swojego konta. Możesz na przykład wysłać wiadomość z potwierdzeniem i przekierować użytkownika do scen, które udostępniają funkcje, które nie wymagają łączenia kont.
  3. Kliknij Zapisz.

  1. W sekcji Warunki kliknij W przypadku wystąpienia błędu systemu lub sieci.
  2. Skonfiguruj proces, jeśli nie można go ukończyć z powodu błędów systemu lub sieci. Możesz na przykład wysłać wiadomość z potwierdzeniem i przekierować użytkownika do scen, które udostępniają funkcje, które nie wymagają łączenia kont.
  3. Kliknij Zapisz.

Obsługiwanie próśb o dostęp do danych

Jeśli żądanie Asystenta zawiera token dostępu, najpierw sprawdź, czy token dostępu jest prawidłowy i nie wygasł, a potem pobierz z bazy danych konta użytkownika konto użytkownika powiązane z tokenem.