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

Typ połączenia „Uproszczone” logowanie przez Google oparte na OAuth dodaje logowanie przez Google do połączenia konta opartego na OAuth. Umożliwia to bezproblemowe łączenie kont za pomocą głosu dla użytkowników Google, a także łączenie kont użytkowników, którzy zarejestrowali się w Twojej usłudze za pomocą tożsamości innej niż Google.

Ten typ połączenia zaczyna się od logowania przez Google, które umożliwia sprawdzenie, czy informacje z profilu Google użytkownika znajdują się w Twoim systemie. Jeśli informacji o użytkowniku nie ma w Twoim systemie, rozpoczyna się standardowy proces OAuth. Użytkownik może też utworzyć nowe konto, korzystając z informacji z profilu Google.

Aby połączyć konta za pomocą uproszczonego połączenia, wykonaj te ogólne czynności:

1. Najpierw poproś użytkownika o zgodę na dostęp do jego profilu Google.
2. Użyj informacji z profilu, aby zidentyfikować użytkownika.
3. Jeśli w systemie uwierzytelniania nie znajdziesz odpowiednika użytkownika Google, proces będzie przebiegać w zależności od tego, czy projekt działania został skonfigurowany w konsoli Actions tak, aby zezwalać na tworzenie kont użytkowników za pomocą głosu, czy tylko na stronie internetowej.
   • 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 zezwalasz na tworzenie konta za pomocą głosu, użytkownik zostanie przekierowany do przeglądarki, w której może otworzyć stronę autoryzacji i dokończyć proces tworzenia konta.

Obsługa tworzenia konta za pomocą głosu

Jeśli zezwalasz na tworzenie kont użytkowników za pomocą głosu, Asystent pyta użytkownika, czy chce:

• utworzyć nowe konto w swoim systemie, używając informacji z konta Google użytkownika,
• Zaloguj się w systemie uwierzytelniania za pomocą innego konta, jeśli użytkownik ma już konto inne niż Google.

Jeśli chcesz zminimalizować trudności związane z procesem tworzenia konta, zalecamy włączenie tworzenia konta za pomocą głosu. Użytkownik musi opuścić przepływ głosowy tylko wtedy, gdy chce zalogować się za pomocą istniejącego konta innego niż Google.

Blokowanie tworzenia konta za pomocą głosu

Jeśli nie zezwolisz na tworzenie kont użytkowników za pomocą głosu, Asystent otworzy adres URL witryny, którą podasz na potrzeby uwierzytelniania użytkowników. Jeśli interakcja odbywa się na urządzeniu bez ekranu, Asystent kieruje użytkownika na telefon, aby kontynuować proces łączenia kont.

Zalecamy zablokowanie tworzenia, jeśli:

• Nie chcesz zezwalać użytkownikom z kontami innymi niż Google na tworzenie nowych kont użytkowników, ale chcesz, aby zamiast tego łączyli się z istniejącymi kontami użytkowników w Twoim systemie uwierzytelniania. Jeśli na przykład oferujesz program lojalnościowy, możesz chcieć mieć pewność, że użytkownik nie straci punktów zgromadzonych na dotychczasowym koncie.

• Musisz mieć pełną kontrolę nad procesem tworzenia konta. Możesz na przykład zablokować tworzenie konta, jeśli podczas tego procesu musisz wyświetlić użytkownikowi warunki usługi.

Wdrożenie uproszczonego łączenia kont za pomocą logowania przez Google opartego na OAuth

Konta są łączone za pomocą standardowych przepływów OAuth 2.0. Actions on Google obsługuje procesy niejawne i z kodem autoryzacji.

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

Konfigurowanie projektu

Aby skonfigurować projekt pod kątem uproszczonego łączenia, wykonaj te czynności:

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

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

   

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

   • Przypisz wartość do pola Identyfikator klienta wydany przez Twoje działania w Google, aby identyfikować żądania pochodzące z Google.
   • Wstaw adresy URL punktów końcowych autoryzacji i wymiany tokenów.

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 会通过包含以下内容的请求将用户发送到您的授权端点： 以下参数：

例如，如果您的授权端点可通过 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:

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

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 dla procesu uwierzytelniania.

Sprawdź, czy użytkownik jest zweryfikowany, i rozpocznij proces łączenia konta.

1. Otwórz projekt w Actions Builder w konsoli Actions.
2. Utwórz nową scenę, aby rozpocząć łączenie kont w swojej akcji:
   1. Kliknij Sceny.
   2. Kliknij ikonę dodawania (+), aby dodać nową scenę.
3. W nowo utworzonej scenie kliknij ikonę dodawania add obok Warunków.
4. Dodaj warunek, który sprawdza, czy użytkownik powiązany z rozmową jest zweryfikowany. Jeśli weryfikacja się nie powiedzie, Akcja nie będzie mogła połączyć kont podczas rozmowy i powinna wrócić do udostępniania funkcji, które nie wymagają łączenia kont.
   1. W polu Enter new expression w sekcji Warunek wpisz tę logikę: user.verificationStatus != "VERIFIED"
   2. W sekcji Przejście wybierz scenę, która nie wymaga połączenia konta, lub scenę, która jest punktem wejścia do funkcji dostępnych tylko dla gości.

1. Kliknij ikonę dodawania add obok pozycji Warunki.
2. Dodaj warunek, który uruchomi 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ę logikę:user.verificationStatus == "VERIFIED"
   2. W sekcji Przejście 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ę systemu łączenia kont.
2. Kliknij Wyślij prompt i dodaj krótkie zdanie, aby wyjaśnić użytkownikowi, dlaczego działanie potrzebuje dostępu do jego tożsamości (np. „Aby zapisać Twoje ustawienia”).
3. Kliknij Zapisz.

1. W sekcji Warunki kliknij Jeśli użytkownik pomyślnie połączy konta.
2. Skonfiguruj, jak ma przebiegać proces, jeśli użytkownik zgodzi się na połączenie konta. Możesz na przykład wywołać webhooka, aby przetworzyć dowolną niestandardową logikę biznesową i wrócić do pierwotnej sceny.
3. Kliknij Zapisz.

1. W sekcji Warunki kliknij Jeśli użytkownik anuluje połączenie konta lub je odrzuci.
2. Skonfiguruj, jak ma przebiegać proces, jeśli użytkownik nie zgodzi się na połączenie konta. Możesz na przykład wysłać wiadomość z potwierdzeniem i przekierować użytkownika do scen, które zapewniają funkcje niewymagające połączenia kont.
3. Kliknij Zapisz.

1. W sekcji Warunki kliknij Jeśli wystąpi błąd systemu lub sieci.
2. Skonfiguruj, jak ma przebiegać 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 zapewniają funkcje niewymagające połączenia kont.
3. Kliknij Zapisz.

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

Jeśli żądanie Asystenta zawiera token dostępu, najpierw sprawdź, czy jest on ważny i nie wygasł, a potem pobierz z bazy danych kont użytkowników konto powiązane z tym tokenem.