Liên kết tài khoản với tính năng đăng nhập bằng Google dựa trên OAuth "Đơn giản hoá" liên kết

Loại liên kết Đăng nhập bằng Google dựa trên OAuth "Hợp lý" sẽ thêm tính năng Đăng nhập bằng Google vào quy trình liên kết tài khoản dựa trên OAuth. Điều này giúp người dùng Google liên kết liền mạch bằng giọng nói, đồng thời cho phép người dùng đã đăng ký dịch vụ của bạn bằng một danh tính không phải của Google liên kết tài khoản.

Loại liên kết này bắt đầu bằng tính năng Đăng nhập bằng Google, cho phép bạn kiểm tra xem thông tin hồ sơ của người dùng trên Google có tồn tại trong hệ thống của bạn hay không. Nếu thông tin của người dùng không có trong hệ thống của bạn, thì quy trình OAuth tiêu chuẩn sẽ bắt đầu. Người dùng cũng có thể chọn tạo một tài khoản mới bằng thông tin trong hồ sơ của họ trên Google.

Hình 1: Sau khi Hành động của bạn có quyền truy cập vào hồ sơ của người dùng trên Google, bạn có thể dùng hồ sơ đó để tìm thông tin khớp với người dùng trong hệ thống xác thực của mình.

Để thực hiện liên kết tài khoản bằng loại Liên kết tinh giản, hãy làm theo các bước chung sau:

1. Trước tiên, hãy yêu cầu người dùng đồng ý cho phép truy cập vào hồ sơ của họ trên Google.
2. Sử dụng thông tin trong hồ sơ của họ để xác định người dùng.
3. Nếu bạn không tìm thấy người dùng Google nào khớp trong hệ thống xác thực của mình, thì quy trình sẽ tiếp tục tuỳ thuộc vào việc bạn đã định cấu hình dự án Hành động trong bảng điều khiển Actions để cho phép tạo tài khoản người dùng thông qua giọng nói hay chỉ trên trang web của bạn.
   • Nếu bạn cho phép tạo tài khoản bằng giọng nói, hãy xác thực mã thông báo nhận dạng nhận được từ Google. Sau đó, bạn có thể tạo một người dùng dựa trên thông tin hồ sơ có trong mã thông báo nhận dạng.
   • Nếu bạn không cho phép tạo tài khoản bằng giọng nói, người dùng sẽ được chuyển đến một trình duyệt nơi họ có thể tải trang uỷ quyền của bạn và hoàn tất quy trình tạo người dùng.

Hình 2. Hình ảnh minh hoạ quy trình OAuth và Đăng nhập bằng Google khi thông tin của người dùng không có trong hệ thống của bạn.

Hỗ trợ tạo tài khoản bằng giọng nói

Nếu bạn cho phép người dùng tạo tài khoản bằng giọng nói, Trợ lý sẽ hỏi người dùng xem họ có muốn làm những việc sau hay không:

• Tạo một tài khoản mới trên hệ thống của bạn bằng thông tin Tài khoản Google của họ, hoặc
• Đăng nhập vào hệ thống xác thực của bạn bằng một tài khoản khác nếu họ có tài khoản không phải của Google.

Bạn nên cho phép tạo tài khoản bằng giọng nói nếu muốn giảm thiểu sự phiền toái trong quy trình tạo tài khoản. Người dùng chỉ cần rời khỏi quy trình thoại nếu muốn đăng nhập bằng một tài khoản không phải của Google.

Không cho phép tạo tài khoản bằng giọng nói

Nếu bạn không cho phép người dùng tạo tài khoản bằng giọng nói, Trợ lý sẽ mở URL đến trang web mà bạn cung cấp để xác thực người dùng. Nếu hoạt động tương tác diễn ra trên một thiết bị không có màn hình, thì Trợ lý sẽ hướng dẫn người dùng chuyển sang điện thoại để tiếp tục quy trình liên kết tài khoản.

Bạn nên không cho phép tạo nếu:

• Bạn không muốn cho phép người dùng có tài khoản không phải của Google tạo tài khoản người dùng mới và muốn họ liên kết với tài khoản người dùng hiện có trong hệ thống xác thực của bạn. Ví dụ: nếu cung cấp một chương trình khách hàng thân thiết, bạn có thể muốn đảm bảo rằng người dùng không mất điểm đã tích luỹ trên tài khoản hiện có của họ.

• Bạn cần có toàn quyền kiểm soát quy trình tạo tài khoản. Ví dụ: bạn có thể không cho phép tạo nếu cần cho người dùng xem điều khoản dịch vụ trong quá trình tạo tài khoản.

Lưu ý: Chọn một trong các lựa chọn về quy trình bên dưới để tìm hiểu thêm về cách triển khai quy trình đã chọn. Nếu cần, nội dung của hướng dẫn sẽ được tải lại để phù hợp với lựa chọn của bạn.

Cho phép tạo tài khoản bằng giọng nói Không cho phép tạo tài khoản bằng giọng nói

Triển khai tính năng liên kết "Đơn giản" Đăng nhập bằng Google dựa trên OAuth

Tài khoản được liên kết bằng các quy trình OAuth 2.0 tiêu chuẩn ngành. Actions on Google hỗ trợ các luồng mã ngầm và uỷ quyền.

Lưu ý: Nếu bạn đang triển khai tính năng liên kết tài khoản để xử lý thông tin tài chính, hãy lưu ý rằng các chính sách bổ sung có thể áp dụng cho Thao tác của bạn. Chúng tôi có thể mất tối đa 6 tuần để xem xét một Thao tác có tính năng liên kết tài khoản đối với thông tin tài chính, vì vậy, hãy tính đến thời gian đó khi lên kế hoạch cho lịch phát hành. Để quy trình xem xét diễn ra dễ dàng hơn, hãy đảm bảo bạn tuân thủ các chính sách về dịch vụ tài chính trước khi gửi Hành động của bạn đi xem xét.

在隐式代码流程中，Google 会在用户浏览器中打开您的授权端点。成功登录后，系统会向 Google 返回长期访问令牌。现在，从 Google 助理向你的 Action 发送的每个请求中都包含此访问令牌。

在授权代码流程中，您需要两个端点：

• 授权端点，该端点负责向尚未登录的用户显示登录界面，并以短期授权代码的形式记录所请求的访问。
• 令牌交换端点，负责两种类型的交换：
  1. 将授权代码交换为长期刷新令牌和短期访问令牌。用户完成帐号关联流程后，系统会进行这种交换。
  2. 将长期刷新令牌换成短期访问令牌。Google 需要新访问令牌时，由于此令牌已过期，因此会进行此交换。

虽然隐式代码流程的实现更简单，但 Google 建议通过隐式流程发出的访问令牌永远不会过期，因为将令牌过期与隐式流程一起使用会强制用户再次关联其帐号。如果出于安全考虑需要令牌到期，强烈建议您考虑使用身份验证代码流程。

注意 ：请选择您希望实施的 OAuth 2.0 流程。如果需要，本指南的内容会根据您的选择重新加载。

身份验证代码 隐式流程

Định cấu hình dự án

Để định cấu hình dự án sử dụng quy trình liên kết tinh giản, hãy làm theo các bước sau:

1. Mở Actions Console rồi chọn dự án mà bạn muốn sử dụng.
2. Nhấp vào thẻ Phát triển rồi chọn Liên kết tài khoản.
3. Bật nút chuyển bên cạnh Liên kết tài khoản.
4. Trong phần Tạo tài khoản, hãy chọn Có.

5. Trong Linking type (Loại liên kết), hãy chọn OAuth & Google Sign In (OAuth và Đăng nhập bằng Google) và Implicit (Ngầm định).

   

6. Trong phần Thông tin khách hàng, hãy làm như sau:

   • Chỉ định một giá trị cho Mã khách hàng do Actions on Google cấp để xác định các yêu cầu đến từ Google.
   • Chèn URL cho các điểm cuối Uỷ quyền và Trao đổi mã thông báo.

7. Nhấp vào Lưu.

Triển khai máy chủ 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。

处理自动关联

在用户同意你的 Action 访问他们的 Google 个人资料后，Google 发送请求，其中包含 Google 用户身份的已签名断言。 该断言包含的信息包括用户的 Google 账号 ID、姓名、 和电子邮件地址。为项目配置的令牌交换端点处理 请求。

如果您的身份验证系统中已经存在相应的 Google 账号， 您的令牌交换端点为用户返回令牌。如果 Google 账号没有 匹配现有用户，您的令牌交换端点会返回 user_not_found 错误。

请求的格式如下：

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

您的令牌交换端点必须能够处理以下参数：

令牌端点参数
grant_type	所交换的令牌的类型。对于这类请求 参数的值为 urn:ietf:params:oauth:grant-type:jwt-bearer。
intent	对于这些请求，此参数的值为 `get`。
assertion	一个 JSON Web 令牌 (JWT)，提供 Google 用户身份。JWT 包含的信息包括 账号 ID、名称和电子邮件地址。
consent_code	可选：一个一次性代码（如果存在）用于表明 用户已同意你的 Action 访问指定范围。
scope	可选：您配置 Google 向用户请求的任何范围。

当您的令牌交换端点收到关联请求时，它应该 以下：

验证和解码 JWT 断言

您可以使用适用于您语言的 JWT 解码库来验证和解码 JWT 断言。 使用 Google 的公钥（适用于 JWK 或 PEM 格式）来验证令牌的 签名。

注意 ：不得对键进行硬编码。而应按照 OpenID Connect Discovery 协议 并检查 cache-control 标头，以确定应将密钥缓存多长时间。

解码后，JWT 断言如以下示例所示：

{
  "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": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

除了验证令牌的签名之外，还要验证断言的颁发者 （iss 字段）为 https://accounts.google.com，且受众群体（aud 字段） 是分配给您的 Action 的客户端 ID。

检查您的身份验证系统中是否已存在该 Google 账号

请检查以下任一条件是否成立：

• Google 账号 ID 可在断言的 sub 字段中找到，也可位于您的用户数据库中。
• 断言中的电子邮件地址与用户数据库中的用户匹配。

如果满足上述任一条件，则表明用户已经注册，您可以发出 访问令牌。

如果断言中指定的 Google 账号 ID 和电子邮件地址都没有 与您数据库中的用户匹配，表示该用户尚未注册。在这种情况下，您的 令牌交换端点应回复 HTTP 401 错误，指定 error=user_not_found， 如以下示例中所示：

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

{
  "error":"user_not_found",
}

当 Google 收到包含 user_not_found 错误的 401 错误响应时， 使用 intent 参数的值调用您的令牌交换端点 设置为 create 并发送包含用户个人资料信息的 ID 令牌 一起发送。

Xử lý việc tạo tài khoản thông qua tính năng Đăng nhập bằng Google

Khi người dùng cần tạo một tài khoản trên dịch vụ của bạn, Google sẽ tạo một đến điểm cuối trao đổi mã thông báo của bạn để chỉ định intent=create, như trong ví dụ sau:

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]

Tham số assertion chứa Mã thông báo web JSON (JWT) cung cấp xác nhận có chữ ký về danh tính của người dùng Google. JWT chứa thông tin bao gồm mã Tài khoản Google, tên và địa chỉ email của người dùng mà bạn có thể sử dụng để tạo một tài khoản mới trên dịch vụ của bạn.

Để phản hồi các yêu cầu tạo tài khoản, điểm cuối trao đổi mã thông báo của bạn phải như sau:

验证和解码 JWT 断言

您可以使用适用于您语言的 JWT 解码库来验证和解码 JWT 断言。 使用 Google 的公钥（适用于 JWK 或 PEM 格式）来验证令牌的 签名。

注意 ：不得对键进行硬编码。而应按照 OpenID Connect Discovery 协议 并检查 cache-control 标头，以确定应将密钥缓存多长时间。

解码后，JWT 断言如以下示例所示：

{
  "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": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

除了验证令牌的签名之外，还要验证断言的颁发者 （iss 字段）为 https://accounts.google.com，且受众群体（aud 字段） 是分配给您的 Action 的客户端 ID。

Xác thực thông tin người dùng và tạo tài khoản mới

Kiểm tra xem một trong các điều kiện sau có đúng hay không:

• Mã Tài khoản Google (trong trường sub của câu nhận định) có trong cơ sở dữ liệu người dùng của bạn.
• Địa chỉ email trong câu nhận định khớp với một người dùng trong cơ sở dữ liệu người dùng của bạn.

Nếu một trong hai điều kiện đúng, hãy nhắc người dùng liên kết tài khoản hiện có của họ với Tài khoản Google của họ bằng cách phản hồi yêu cầu với lỗi HTTP 401, trong đó chỉ định error=linking_error và địa chỉ email của người dùng là login_hint, như trong ví dụ sau:

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

{
  "error":"linking_error",
  "login_hint":"[e-mail]"
}

Nếu không có điều kiện nào đúng, hãy tạo một tài khoản người dùng mới bằng thông tin này được cung cấp trong JWT. Các tài khoản mới thường chưa đặt mật khẩu. Đó là bạn nên thêm tính năng Đăng nhập bằng Google vào các nền tảng khác để người dùng có thể đăng nhập trong thông qua Google trên các nền tảng của ứng dụng. Ngoài ra, bạn có thể gửi cho người dùng một đường liên kết bắt đầu quy trình khôi phục mật khẩu để cho phép người dùng thiết lập mật khẩu để đăng nhập trên các nền tảng khác.

Khi quá trình tạo hoàn tất, hãy cấp một mã truy cập rồi trả về các giá trị trong đối tượng JSON trong nội dung của phản hồi HTTPS, như trong ví dụ sau:

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

Thiết kế giao diện người dùng bằng giọng nói cho quy trình xác thực

Cảnh báo: Đừng đưa ra lời nhắc bắt buộc liên kết tài khoản cho người dùng khi bắt đầu cuộc trò chuyện với Hành động của bạn. Thay vào đó, hãy cung cấp cho người dùng chưa xác thực một quy trình dành cho khách để cho họ thấy cách Hành động của bạn hoạt động, sau đó chỉ yêu cầu liên kết tài khoản nếu cần thiết để tiếp tục. Nếu người dùng liên tục rời khỏi Lệnh hành động do gặp vấn đề về việc liên kết tài khoản, thì Google sẽ không tích cực quảng bá Lệnh hành động đó, điều này có thể làm giảm lưu lượng truy cập của người dùng vào Lệnh hành động.

Lưu ý: Bạn phải sử dụng Actions Builder để tạo một Thao tác triển khai tính năng liên kết tài khoản.

Kiểm tra xem người dùng đã được xác minh hay chưa và bắt đầu quy trình liên kết tài khoản

1. Mở dự án Actions Builder trong Bảng điều khiển Actions.
2. Tạo một cảnh mới để bắt đầu liên kết tài khoản trong Thao tác của bạn:
   1. Nhấp vào Cảnh.
   2. Nhấp vào biểu tượng thêm (+) để thêm một cảnh mới.
3. Trong cảnh mới tạo, hãy nhấp vào biểu tượng thêm cho Điều kiện.
4. Thêm một điều kiện để kiểm tra xem người dùng liên kết với cuộc trò chuyện có phải là người dùng đã xác minh hay không. Nếu quy trình kiểm tra không thành công, Hành động của bạn sẽ không thể thực hiện quy trình liên kết tài khoản trong cuộc trò chuyện và phải quay lại cung cấp quyền truy cập vào chức năng không yêu cầu liên kết tài khoản.
   1. Trong trường Enter new expression trong mục Điều kiện, hãy nhập logic sau: user.verificationStatus != "VERIFIED"
   2. Trong phần Chuyển cảnh, hãy chọn một cảnh không yêu cầu liên kết tài khoản hoặc một cảnh là điểm truy cập vào chức năng chỉ dành cho khách.

1. Nhấp vào biểu tượng thêm cho Điều kiện.
2. Thêm một điều kiện để kích hoạt quy trình liên kết tài khoản nếu người dùng không có danh tính được liên kết.
   1. Trong trường Enter new expression trong mục Điều kiện, hãy nhập logic sau: user.verificationStatus == "VERIFIED"
   2. Trong mục Chuyển đổi, hãy chọn cảnh hệ thống Liên kết tài khoản.
   3. Nhấp vào Lưu.

Sau khi lưu, một cảnh liên kết tài khoản mới có tên là <SceneName>_AccountLinking sẽ được thêm vào dự án của bạn.

Tuỳ chỉnh cảnh liên kết tài khoản

1. Trong mục Cảnh, hãy chọn cảnh hệ thống liên kết tài khoản.
2. Nhấp vào Gửi câu lệnh rồi thêm một câu ngắn để mô tả cho người dùng lý do Hành động cần truy cập vào danh tính của họ (ví dụ: "Để lưu các lựa chọn ưu tiên của bạn").
3. Nhấp vào Lưu.

1. Trong mục Điều kiện, hãy nhấp vào Nếu người dùng hoàn tất việc liên kết tài khoản.
2. Định cấu hình cách quy trình sẽ diễn ra nếu người dùng đồng ý liên kết tài khoản của họ. Ví dụ: gọi webhook để xử lý mọi logic nghiệp vụ tuỳ chỉnh cần thiết và chuyển về cảnh ban đầu.
3. Nhấp vào Lưu.

1. Trong mục Điều kiện, hãy nhấp vào Nếu người dùng huỷ hoặc đóng tính năng liên kết tài khoản.
2. Định cấu hình cách quy trình sẽ diễn ra nếu người dùng không đồng ý liên kết tài khoản của họ. Ví dụ: gửi một thông báo xác nhận và chuyển hướng đến những cảnh cung cấp chức năng không yêu cầu liên kết tài khoản.
3. Nhấp vào Lưu.

1. Trong mục Điều kiện, hãy nhấp vào Nếu xảy ra lỗi hệ thống hoặc lỗi mạng.
2. Định cấu hình cách luồng nên tiếp tục nếu không thể hoàn tất luồng liên kết tài khoản do lỗi hệ thống hoặc lỗi mạng. Ví dụ: gửi một thông báo xác nhận và chuyển hướng đến những cảnh cung cấp chức năng không yêu cầu liên kết tài khoản.
3. Nhấp vào Lưu.

Xử lý yêu cầu truy cập dữ liệu

Nếu yêu cầu của Trợ lý có chứa mã truy cập, trước tiên, hãy kiểm tra để đảm bảo mã truy cập đó hợp lệ và chưa hết hạn, sau đó truy xuất tài khoản người dùng được liên kết với mã đó từ cơ sở dữ liệu tài khoản người dùng của bạn.