Łą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

为了支持 OAuth 2.0 隐式流程，您的服务会进行授权 端点。此端点负责 就数据访问征得用户同意。授权端点 向尚未登录的用户显示登录界面，并记录 同意所请求的访问。

当您的 Action 需要调用您的某项授权的 API 时，Google 会使用 此端点来获得用户许可，以在其上调用这些 API 。

由 Google 发起的典型 OAuth 2.0 隐式流会话具有以下特征： 以下流程：

  1. Google 会在用户的浏览器中打开您的授权端点。通过 如果用户尚未登录，则可以登录，并且授予 Google 访问 通过您的 API 访问其数据（如果尚未授予权限）。
  2. 您的服务会创建一个访问令牌并将其返回给 通过使用访问令牌将用户的浏览器重定向回 Google， 附件。
  3. Google 调用您的服务的 API，并使用 。您的服务会验证访问令牌是否向 Google 授予 访问 API 的授权，然后完成 API 调用。

处理授权请求

当您的 Action 需要通过 OAuth 2.0 隐式流程执行账号关联时， Google 会通过包含以下内容的请求将用户发送到您的授权端点： 以下参数：

授权端点参数
client_id 您分配给 Google 的客户 ID。
redirect_uri 此请求的响应发送到的网址。
state 将一个在 重定向 URI。
response_type 要在响应中返回的值的类型。对于 OAuth 2.0 隐式 则响应类型始终为 token。

例如，如果您的授权端点可通过 https://myservice.example.com/auth 访问， 请求可能如下所示：

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

为了让授权端点能够处理登录请求，请执行以下步骤：

  1. 验证 client_id 和 redirect_uri 值， 防止向意外或配置错误的客户端应用授予访问权限：

    • 确认 client_id 是否与您的客户端 ID 匹配 分配给 Google。
    • 确认 redirect_uri 指定的网址 参数的格式如下： 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      YOUR_PROJECT_ID 是项目设置页面上的 ID Actions 控制台界面。

  2. 检查用户是否已登录您的服务。如果用户未登录 中，完成服务的登录或注册流程。

  3. 生成 Google 将用于访问您的 API 的访问令牌。通过 访问令牌可以是任何字符串值，但必须唯一地表示 令牌对应的用户和客户端，且不得被猜到。

  4. 发送 HTTP 响应，将用户浏览器重定向到相应网址 由 redirect_uri 参数指定。添加所有 以下参数：

    • access_token：您刚刚生成的访问令牌
    • token_type：字符串 bearer
    • state：原始状态的未修改状态值 请求 以下是生成的网址示例： 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google 的 OAuth 2.0 重定向处理程序将收到访问令牌并确认 state 值没有更改。在 Google 获得 访问令牌，则 Google 会将该令牌附加到后续调用 作为 AppRequest 的一部分添加到您的 Action。

Obsługa automatycznego łączenia

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

Jeśli w systemie uwierzytelniania już istnieje odpowiednie konto Google, punkt końcowy wymiany tokenów zwraca token użytkownika. Jeśli konto Google nie pasujące do istniejącego użytkownika, punkt końcowy wymiany tokenów zwraca błąd user_not_found.

Prośba ma taki format:

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 wymiany tokenów musi obsługiwać te parametry:

Parametry punktu końcowego tokena
grant_type Typ wymienianego tokena. W przypadku tych żądań 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), który stanowi podpisane potwierdzenie uwierzytelniania Google tożsamości użytkownika. Token JWT zawiera informacje o Google użytkownika Identyfikator konta, imię i nazwisko oraz adres e-mail.
consent_code Opcjonalnie: jeśli jest dostępny, jednorazowy kod, który wskazuje, że użytkownik wyraził zgodę na dostęp Twojej akcji do określonych zakresów.
scope Opcjonalne: wszystkie zakresy skonfigurowane przez Google, aby żądać od użytkowników.

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

Weryfikowanie i dekodowanie potwierdzenia JWT

Potwierdzenie JWT możesz zweryfikować i zdekodować za pomocą biblioteki dekodowania JWT dla swojego języka. Użyj kluczy publicznych Google (dostępnych w językach JWK lub PEM), aby zweryfikować token podpis.

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

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

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

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

  • Identyfikator konta Google znajdujący się w polu sub potwierdzenia znajduje się w bazie danych użytkowników.
  • Adres e-mail podany w potwierdzeniu pasuje do użytkownika w bazie danych użytkowników.

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

Jeśli ani identyfikator konta Google, ani adres e-mail podany w potwierdzeniu pasuje do użytkownika w bazie danych, nie zarejestrował się jeszcze. W takim przypadku atrybut Punkt końcowy wymiany tokenów powinien odpowiedzieć z błędem 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, Google wywołuje punkt końcowy wymiany tokenów wartością parametru intent ustaw na create (utwórz) i wysyłaj token tożsamości zawierający informacje o profilu użytkownika; z prośbą o pozwolenie.

Utwórz konto za pomocą Logowania przez Google

Gdy użytkownik musi utworzyć konto w Twojej usłudze, Google żądanie do punktu końcowego 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 udostępnia podpisane potwierdzenie tożsamości użytkownika Google. Token JWT zawiera informacje obejmujący identyfikator konta Google użytkownika, imię i nazwisko oraz adres e-mail, aby utworzyć nowe konto w usłudze.

Aby odpowiadać na żądania utworzenia konta, punkt końcowy wymiany tokenów musi wykonać następujące:

Weryfikowanie i dekodowanie potwierdzenia JWT

Potwierdzenie JWT możesz zweryfikować i zdekodować za pomocą biblioteki dekodowania JWT dla swojego języka. Użyj kluczy publicznych Google (dostępnych w językach JWK lub PEM), aby zweryfikować token podpis.

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

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

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

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

  • Identyfikator konta Google znajdujący się w polu sub potwierdzenia znajduje się w bazie danych użytkowników.
  • Adres e-mail podany w potwierdzeniu pasuje do użytkownika w bazie danych użytkowników.

Jeśli którykolwiek z tych warunków jest spełniony, poproś użytkownika o połączenie istniejącego konta swojego konta Google, odpowiadając na żądanie z błędem HTTP 401, określając error=linking_error, a adres e-mail użytkownika w polu login_hint, na przykład następujący przykład:

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 przy użyciu tych informacji podane w tokenie JWT. Nowe konta zwykle nie mają ustawionego hasła. Jest zalecamy dodanie Logowania przez Google na innych platformach, aby umożliwić użytkownikom logowanie w różnych miejscach aplikacji. Ewentualnie możesz wyślij użytkownikowi e-maila z linkiem, który rozpoczyna proces odzyskiwania hasła, aby umożliwić użytkownikowi ustawienie hasła do logowania się na innych platformach.

Po zakończeniu tworzenia wydaj token dostępu i zwracają wartości w obiekcie JSON w treść 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.