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 các quy trình ngầm ẩn và mã uỷ quyền OAuth 2.0 theo tiêu chuẩn ngành. 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 关联流程托管的用户屏幕的设计要求和建议。在 Google 应用调用该 API 后，您的平台会向用户显示登录 Google 页面和账号关联意见征求界面。同意关联账号后，系统会将用户重定向回 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 的徽标，请参阅徽标和商标。

Create the project

To create your project to use account linking:

1. Go to the Google API Console.
2. Click Create project.
3. Enter a name or accept the generated suggestion.
4. Confirm or edit any remaining fields.
5. Click Create.

To view your project ID:

1. Go to the Google API Console.
2. Find your project in the table on the landing page. The project ID appears in the ID column.

Configure your OAuth Consent Screen

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

1. Open the OAuth consent screen page of the Google APIs console.
2. If prompted, select the project you just created.

3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

   Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

   Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

   Support email: For users to contact you with questions about their consent.

   Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

   Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

   Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

   Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

   Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

   

   Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

Triển khai máy chủ OAuth

Để hỗ trợ quy trình ngầm OAuth 2.0, dịch vụ của bạn sẽ thực hiện uỷ quyền điểm cuối được cung cấp bởi HTTPS. Điểm cuối này chịu trách nhiệm xác thực và có được sự đồng ý của người dùng về việc truy cập dữ liệu. Điểm cuối uỷ quyền biểu 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 đồng ý với quyền truy cập được yêu cầu.

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

Một phiên luồng quy trình ngầm ẩn OAuth 2.0 điển hình do Google khởi tạo có quy trình sau:

1. Google sẽ mở điểm cuối uỷ quyền của bạn trong trình duyệt của người dùng. Chiến lược phát hành đĩa đơn 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 sẽ tạo mã truy cập rồi trả lại 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 bằng quyền truy cập 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 bằng từng yêu cầu. Dịch vụ của bạn xác minh rằng mã truy cập cấp cho Google uỷ quyền truy cập 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 qua OAuth 2.0 luồng ngầm ẩn, Google sẽ chuyển người dùng đến điểm cuối uỷ quyền của bạn bằng bao gồm các thông số sau:

Ví dụ: nếu điểm cuối uỷ quyền của bạn có tại https://myservice.example.com/auth, một 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 có thể xử lý các yêu cầu đăng nhập, hãy làm như sau các bước:

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

   • Xác nhận rằng client_id khớp với mã ứng dụng khách mà bạn được chỉ định cho Google.
   • Xác nhận rằng URL do redirect_uri chỉ định thông số đó có dạng như 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 chưa. Nếu người dùng chưa ký hãy hoàn tất quy trình đăng nhập hoặc đăng ký dịch vụ của bạn.

3. Tạo mã truy cập cho Google dùng để truy cập vào API của bạn. Chiến lược phát hành đĩa đơn mã truy cập có thể là bất kỳ giá trị chuỗi nào, nhưng mã này phải thể hiện duy nhất người dùng và máy khách của mã thông báo đó và không được phép đoán.

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. Bao gồm tất cả các tham số sau trong phân đoạn URL:

   • access_token: Mã truy cập bạn vừa tạo
   • token_type: Chuỗi bearer
   • state: Giá trị trạng thái chưa được sửa đổi của giá trị gốc yêu cầ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 được mã truy cập và xác nhận rằng giá trị state không thay đổi. Sau khi Google có được mã truy cập của dịch vụ của bạn, Google sẽ đính kèm mã này vào các lệnh gọi tiếp theo cho các API dịch vụ của bạn.

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.

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. 点击配置 settings 以打开 OAuth 2.0 配置窗口。
2. 在 OAuth flow 字段中，选择 Client-side（客户端）。
3. 在 OAuth 端点字段中，选择自定义。
4. 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
5. 在第 1 步部分，不要选择任何 Google 范围。请将此字段留空或输入对服务器有效的范围（如果您不使用 OAuth 范围，则可以输入任意字符串）。完成后，点击授权 API。
6. 在 Step 2 和 Step 3 部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

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

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

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