Liên kết Tài khoản Google với OAuth

Các tài khoản được liên kết bằng quy trình ngầm định và mã uỷ quyền OAuth 2.0 theo tiêu chuẩn ngành.

Thận trọng: Luồng cấp quyền trực tiếp không được hỗ trợ cho MCP, UCP và luồng do Agent điều khiển. Nhìn chung, bạn không nên sử dụng phương thức này cho tất cả các hoạt động tích hợp mới. Thay vào đó, hãy sử dụng quy trình mã uỷ quyền.

Dịch vụ của bạn phải hỗ trợ các điểm cuối uỷ quyền và trao đổi mã thông báo tuân thủ OAuth 2.0.

在 隐式 流程中，Google 会在用户的浏览器中打开您的授权端点。成功登录后，您会向 Google 返回长期有效的访问令牌。此访问令牌现在包含在 Google 发送的每个请求中。

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

• 授权 端点，用于向尚未登录的用户显示登录界面。授权端点还会创建一个短期有效的授权代码，以记录用户对所请求访问权限的同意情况。

• 令牌交换 端点，负责两种类型的交换：

  1. 将授权代码交换为长期有效的刷新令牌和短期有效的访问令牌。当用户完成账号关联流程时，会发生此交换。
  2. 将长期有效的刷新令牌交换为短期有效的访问令牌。 当 Google 需要新的访问令牌（因为其拥有的访问令牌已过期）时，会发生此交换。

选择 OAuth 2.0 流程

虽然 隐式 流程的实现较为简单，但 Google 建议通过隐式流程颁发的访问令牌永不过期。这是因为，如果令牌通过隐式流程过期，用户就必须再次关联其账号。如果您出于安全原因需要令牌过期，我们强烈建议您改用 授权代码 流程。

**注意** ：使用以下按钮选择要 实现的 OAuth 2.0 流程。如有需要，本指南的内容将重新加载以匹配您的选择。

隐式流程 授权代码

设计准则

本部分介绍了您为 OAuth 关联流程托管的用户界面的设计要求和建议。在 Google 的应用调用后，您的平台会向用户显示“登录 Google”页面和账号关联同意屏幕。用户同意关联账号后，系统会将用户重定向回 Google 的应用。

图 1.账号关联用户登录 Google 和同意屏幕。

要求

1. 您必须说明，用户的账号将与 Google 关联， 而不是与 Google Home 或 Google 助理等特定 Google 产品关联。

建议

建议您执行以下操作：

1. 显示 Google 的隐私权政策。在权限请求页面上添加指向 Google 的隐私权政策 的链接。

2. 要共享的数据。 使用清晰简洁的语言告知用户 Google 需要哪些数据及其原因。

3. 明确的号召性用语。 在同意屏幕上添加明确的号召性用语，例如“同意并关联”。 这是因为用户需要了解他们需要与 Google 共享哪些数据才能关联其账号。

4. 能够取消。 为用户提供返回或取消的方式（如果他们选择不关联）。

5. 清晰的登录流程。 确保用户有清晰的 Google 账号登录方法，例如用户名和密码字段，或 “使用 Google 账号登录”。

6. 能够取消关联。 为用户提供取消关联的机制，例如指向您平台上账号设置的网址。或者，您可以 添加指向 Google 账号的链接，用户 可以在其中管理其关联的账号。

7. 能够更改用户账号。 为用户提供切换账号的方法。如果用户倾向于拥有多个账号，这一点尤其有用。

   • 如果用户必须关闭权限请求页面才能切换账号，请向 Google 发送可恢复的错误，以便用户可以使用 OAuth 关联 和 隐式 流程登录所选账号。

8. 添加您的徽标。 在权限请求页面上显示您的公司徽标。请按照您的样式指南放置徽标。如果您想要或需要 同时显示 Google 的徽标，请参阅 徽标和商标。

图 2.用户登录 Google 和同意 屏幕 的设计准则。

创建项目

**注意**： 您可以重复使用现有项目，无需专门为账号关联创建新项目。

如需创建项目以使用账号关联，请执行以下操作：

1. 前往 Google API 控制台。
2. 点击 Create project 。
3. 输入名称或接受生成的建议。
4. 确认或修改任何剩余字段。
5. 点击创建 。

如需查看项目 ID，请执行以下操作：

1. 前往 Google API 控制台。
2. 在着陆页的表格中找到您的项目。项目 ID 会显示在 ID 列中。

配置 OAuth 权限请求页面

Google 账号关联过程包含一个权限请求页面，该页面会告知用户请求访问其数据的应用、应用请求的数据类型以及适用的条款。您需要先配置 OAuth 权限请求页面，然后才能生成 Google API 客户端 ID。

1. 打开 Google API 控制台的 OAuth 权限请求页面 页面。
2. 如果系统提示您选择项目，请选择您刚刚创建的项目。

3. 在“OAuth 权限请求页面”上，填写表单，然后点击“保存”按钮。

   应用名称 ：向用户征求同意的应用的名称。该名称应准确反映您的应用，并且与用户在其他位置看到的应用名称保持一致。应用名称将显示在账号关联权限请求页面上。

   应用徽标：权限请求页面上显示的一张图片，用以让用户认出您的应用。徽标会显示在账号关联权限请求页面和账号设置中

   支持邮箱 ：用户用于针对其同意问题与您联系的邮箱。

   Google API 的范围 ：范围允许您的应用访问用户的私有 Google 数据。对于 Google 账号关联用例，默认范围（邮箱、个人资料、openid）就足够了，您无需添加任何敏感范围。通常，最佳做法是在需要访问权限时逐步请求范围，而不是提前请求。了解详情。

   已获授权的网域 ：为了保护您和您的用户，Google 只允许使用 OAuth 进行身份验证的应用使用已获授权的网域。您应用的链接必须托管在已获授权的网域上。了解详情。

   应用首页链接 ：应用的首页。必须托管在已获授权的网域上。

   应用隐私权政策链接 ：显示在 Google 账号关联权限请求页面上。必须托管在已获授权的网域上。

   应用服务条款链接（可选） ：必须托管在已获授权的网域上。

   

   图 1. 虚构应用 Tunery 的 Google 账号关联权限请求页面

4. 查看“验证状态”，如果您的应用需要验证，请点击“提交以进行验证”按钮，提交应用以进行验证。如需了解详情，请参阅 OAuth 验证要求。

Triển khai máy chủ OAuth

n

Nguy hiểm: Luồng cấp quyền trực tiếp không được hỗ trợ cho MCP, UCP và các quy trình do Tác nhân điều khiển. Nhìn chung, bạn không nên sử dụng quy trình này cho tất cả các công cụ tích hợp mới do lý do bảo mật. Thay vào đó, hãy sử dụng quy trình sử dụng mã uỷ quyền thay thế.

Để hỗ trợ quy trình ngầm định OAuth 2.0, dịch vụ của bạn sẽ cung cấp một điểm cuối uỷ quyền bằng HTTPS. Điểm cuối này chịu trách nhiệm xác thực và thu thập sự đồng ý của người dùng để có quyền truy cập dữ liệu. Điểm cuối uỷ quyền sẽ hiển thị giao diện người dùng đăng nhập cho những người dùng chưa đăng nhập và ghi lại sự đồng ý đối với quyền truy cập được yêu cầu.

Khi một ứng dụng của Google cần gọi một trong các API được uỷ quyền của dịch vụ, Google sẽ sử dụng điểm cuối này để được người dùng cho phép gọi các API này thay mặt họ.

Liên kết tài khoản Google: Quy trình ngầm định OAuth

Sơ đồ trình tự sau đây trình bày chi tiết về các tương tác giữa Người dùng, Google và các điểm cuối của dịch vụ.

Figure 1. Trình tự các sự kiện trong luồng cấp quyền trực tiếp OAuth 2.0 để liên kết Tài khoản Google.

Vai trò và trách nhiệm

Bảng sau đây xác định vai trò và trách nhiệm của các tác nhân trong luồng cấp quyền trực tiếp OAuth của tính năng liên kết Tài khoản Google (GAL). Xin lưu ý rằng trong GAL, Google đóng vai trò là Ứng dụng OAuth, trong khi dịch vụ của bạn đóng vai trò là Nhà cung cấp dịch vụ/danh tính.

Tác nhân / Thành phần	Vai trò GAL	Yêu cầu của công việc
Ứng dụng / Máy chủ của Google	Ứng dụng OAuth	Khởi động quy trình, nhận mã truy cập bằng cách chuyển hướng trình duyệt, và lưu trữ mã đó một cách an toàn để truy cập vào các API của dịch vụ.
Điểm cuối uỷ quyền	Máy chủ uỷ quyền	Xác thực người dùng, thu thập sự đồng ý của họ và cấp mã truy cập dài hạn trực tiếp cho Google.
URI chuyển hướng của Google	Điểm cuối gọi lại	Nhận yêu cầu chuyển hướng người dùng từ dịch vụ uỷ quyền của bạn với các giá trị access_token và state trong đoạn URL.

Một phiên quy trình ngầm định OAuth 2.0 thông thường do Google khởi động có quy trình như sau:

1. Google mở điểm cuối uỷ quyền của bạn trong trình duyệt của người dùng. Người dùng đăng nhập (nếu chưa đăng nhập) và cấp cho Google quyền truy cập vào dữ liệu của họ bằng API của bạn (nếu họ chưa cấp quyền).
2. Dịch vụ của bạn tạo một mã truy cập và trả về mã đó cho Google. Để thực hiện việc này, hãy chuyển hướng trình duyệt của người dùng trở lại Google với mã truy cập được đính kèm vào yêu cầu.
3. Google gọi các API của dịch vụ và đính kèm mã truy cập với mỗi yêu cầu. Dịch vụ của bạn xác minh rằng mã truy cập cấp cho Google quyền truy cập vào API, sau đó hoàn tất lệnh gọi API.

Xử lý yêu cầu uỷ quyền

Khi một ứng dụng của Google cần thực hiện liên kết tài khoản bằng luồng cấp quyền trực tiếp OAuth 2.0, Google sẽ gửi người dùng đến điểm cuối uỷ quyền của bạn bằng một yêu cầu bao gồm các tham số sau:

Tham số điểm cuối uỷ quyền
client_id	Mã ứng dụng mà bạn đã chỉ định cho Google.
redirect_uri	URL mà bạn gửi phản hồi cho yêu cầu này.
state	Giá trị kế toán được chuyển trở lại Google mà không thay đổi trong URI chuyển hướng.
response_type	Loại giá trị cần trả về trong phản hồi. Đối với quy trình ngầm định OAuth 2.0 flow, loại phản hồi luôn là token.
user_locale	Chế độ cài đặt ngôn ngữ của Tài khoản Google ở RFC5646 định dạng dùng để bản địa hoá nội dung của bạn theo ngôn ngữ ưu tiên của người dùng.

Ví dụ: nếu điểm cuối uỷ quyền của bạn có tại https://myservice.example.com/auth, thì yêu cầu có thể có dạng như sau:

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

Để điểm cuối uỷ quyền của bạn xử lý các yêu cầu đăng nhập, hãy làm theo các bước sau:

1. Xác minh các giá trị client_id và redirect_uri để ngăn việc cấp quyền truy cập cho các ứng dụng không mong muốn hoặc ứng dụng khách được định cấu hình sai:

   • Xác nhận rằng client_id khớp với mã ứng dụng mà bạn đã chỉ định cho Google.
   • Xác nhận rằng URL do tham số redirect_uri chỉ định có dạng sau:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

2. Kiểm tra xem người dùng đã đăng nhập vào dịch vụ của bạn hay chưa. Nếu người dùng chưa đăng nhập, hãy hoàn tất quy trình đăng nhập hoặc đăng ký của dịch vụ.

3. Tạo mã truy cập để Google sử dụng nhằm truy cập vào API của bạn. Mã truy cập có thể là bất kỳ giá trị chuỗi nào , nhưng phải đại diện duy nhất cho người dùng và ứng dụng mà mã đó dành cho, đồng thời không được đoán được.

4. Gửi phản hồi HTTP chuyển hướng trình duyệt của người dùng đến URL do tham số redirect_uri chỉ định. Đưa tất cả các tham số sau vào phân mảnh của URL:

   • access_token: Mã truy cập mà bạn vừa tạo
   • token_type: Chuỗi bearer
   • state: Giá trị trạng thái không sửa đổi từ yêu cầu ban đầu

   Sau đây là ví dụ về URL kết quả:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Trình xử lý chuyển hướng OAuth 2.0 của Google nhận mã truy cập và xác nhận rằng giá trị state không thay đổi. Sau khi Google nhận được mã truy cập cho dịch vụ của bạn, Google sẽ đính kèm mã đó vào các lệnh gọi tiếp theo đến các API của dịch vụ.

Xử lý các yêu cầu thông tin người dùng

Điểm cuối userinfo là một tài nguyên được bảo vệ bằng OAuth 2.0. Tài nguyên này trả về các thông báo xác nhận quyền sở hữu về người dùng được liên kết. Việc triển khai và lưu trữ điểm cuối userinfo là không bắt buộc, ngoại trừ các trường hợp sử dụng sau:

• Đăng nhập vào tài khoản được liên kết bằng tính năng Google One Chạm.
• Gói thuê bao dễ dàng trên Android TV.

Sau khi đã truy xuất thành công mã truy cập từ điểm cuối của mã thông báo, Google sẽ gửi yêu cầu đến điểm cuối userinfo của bạn để truy xuất thông tin hồ sơ cơ bản về người dùng được liên kết.

tiêu đề của yêu cầu điểm cuối userinfo
Authorization header	Mã truy cập thuộc loại Bearer.

Ví dụ: nếu điểm cuối userinfo của bạn có sẵn tại https://myservice.example.com/userinfo, một yêu cầu có thể có dạng như sau:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

Để điểm cuối userinfo xử lý các yêu cầu, hãy làm theo các bước sau:

1. Trích xuất mã truy cập từ tiêu đề Uỷ quyền và trả về thông tin cho người dùng được liên kết với mã truy cập.
2. Nếu mã truy cập không hợp lệ, hãy trả về lỗi HTTP 401 unauthorized (Không được phép sử dụng tiêu đề phản hồi WWW-Authenticate). Dưới đây là ví dụ về phản hồi khi xảy ra lỗi thông tin người dùng:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   Nếu phản hồi 401 Trái phép hoặc bất kỳ lỗi không thành công nào khác được trả về trong quá trình liên kết, thì lỗi này sẽ không khôi phục được, mã thông báo đã truy xuất sẽ bị loại bỏ và người dùng sẽ phải bắt đầu lại quy trình liên kết.

3. Nếu mã truy cập hợp lệ, hãy trả về và phản hồi HTTP 200 kèm theo đối tượng JSON sau trong phần nội dung của HTTPS trả lời:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   Nếu điểm cuối userinfo của bạn trả về phản hồi thành công HTTP 200, thì mã thông báo và các thông báo xác nhận quyền sở hữu đã truy xuất sẽ được đăng ký vào Tài khoản Google của người dùng.

   phản hồi của thiết bị đầu cuối userinfo
   sub	Mã nhận dạng duy nhất giúp nhận dạng người dùng trong hệ thống của bạn.
   email	Địa chỉ email của người dùng.
   given_name	Không bắt buộc: Tên của người dùng.
   family_name	Không bắt buộc: Họ của người dùng.
   name	Không bắt buộc: Tên đầy đủ của người dùng.
   picture	Không bắt buộc: Ảnh hồ sơ của người dùng.

Xác thực quá trình triển khai

您可以使用 OAuth 2.0 Playground 工具验证您的实现。

在该工具中，执行以下步骤：

1. 点击配置 以打开“OAuth 2.0 配置”窗口。
2. 在 OAuth flow（OAuth 流程）字段中，选择 Client-side（客户端）。
3. 在 OAuth Endpoints 字段中，选择 Custom。
4. 在相应字段中指定您的 OAuth 2.0 端点以及您分配给 Google 的客户端 ID。
5. 在第 1 步部分中，请勿选择任何 Google 范围。请将此字段留空，或输入适用于您服务器的范围（如果您不使用 OAuth 范围，则输入任意字符串）。完成后，点击 Authorize APIs。
6. 在第 2 步和第 3 步部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示工具验证您的实现。

在该工具中，执行以下步骤：

1. 点击使用 Google 账号登录按钮。
2. 选择您要关联的账号。
3. 输入服务 ID。
4. （可选）输入您将请求访问的一个或多个范围。
5. 点击开始演示。
6. 当系统提示时，请确认您可以同意或拒绝关联请求。
7. 确认您已重定向到相应平台。