概览

通过帐号关联，Google 帐号持有人可以快速、顺畅、安全地连接到您的服务。您可以选择实现 Google 帐号关联，以便与 Google 应用和服务共享您平台中的用户数据。

通过安全的 OAuth 2.0 协议，您可以安全地将用户的 Google 帐号与其平台上的帐号关联起来，从而授予 Google 应用和设备访问您的服务的权限。

用户可以通过 Google 帐号关联，在您的平台上关联或解除关联的帐号，并可以选择在平台上创建一个新帐号。

使用场景

实施 Google 帐号关联的部分原因如下：

• 与 Google 应用和服务共享您平台中的用户数据。

• 使用 Google TV 播放您的视频和电影内容。

• 使用 Google Home 应用和 Google 助理“控制 Google 开灯”来管理和控制 Google 智能家居已连接的设备。

• 通过对话型 Action 为用户打造个性化的 Google 助理体验和功能：“Ok Google，从我常去的星巴克订餐”。

• 让用户能够在将其 Google 帐号与奖励合作伙伴帐号关联后，观看 YouTube 上的符合条件的直播，从而赢取奖励。

• 在注册期间，使用 Google 帐号个人资料中一致的共享数据预先填充新帐号。

支持的功能

Google 帐号关联支持以下功能：

• 使用 OAuth 链接隐式流程快速轻松地共享您的数据。

• 利用 OAuth 关联授权代码流程提供更好的安全性。

• 登录现有用户，或者向 Google 注册新用户到您的平台，征得他们的同意，并通过精简关联安全地共享数据。

• 应用快速关联可减少用户的不便。在受信任的 Google 应用中，轻轻一点即可安全地打开经过验证的 Android 或 iOS 应用，轻轻一点即可授权用户并关联帐号。

• 通过定义自定义范围以仅共享必要的数据来增强用户隐私保护，通过明确定义数据的使用方式来增强用户信任。

• 通过解除关联帐号，可以撤消对托管在您的平台上的数据和服务的访问权限。通过实现可选的令牌撤消端点，您可以与 Google 发起的事件保持同步；而借助跨帐号保护功能 (RISC)，您可以在平台中发生任何解除关联事件时通知 Google。

注意：Google Identity Platform 的 OAuth 2.0 文档大多介绍了如何使用用户的 Google 帐号登录，以及如何获取代表他们调用 Google API 的授权。Google 帐号关联涵盖了反转情况，即允许 Google 服务的用户向您的平台进行身份验证并调用您的服务的 API。如果您想使用 OAuth 2.0 访问 Google API，请参阅 OAuth 2.0 客户端文档。

帐号关联流程

Google 帐号关联流程有 3 种，都是基于 OAuth，均要求您管理或控制符合 OAuth 2.0 规范的授权和令牌交换端点。

在关联过程中，您需要在获得帐号持有人同意关联帐号并共享数据后，为 Google 普通帐号颁发访问令牌。

OAuth 关联 ('Web OAuth)

这是将用户转到您的网站进行关联的基本 OAuth 流程。用户被重定向至您的网站以登录其帐号。登录后，用户会同意与您的服务共享您在 Google 服务中的数据。此时，用户的 Google 帐号与您的服务已关联。

OAuth 关联支持授权代码和隐式 OAuth 流程。您的服务必须为隐式流程托管符合 OAuth 2.0 规范的授权端点，并且在使用授权代码流程时必须公开授权和令牌交换端点。

注意：所有帐号关联集成都必须实现 Web OAuth，因为它是应用快速关联和精简流程的后备方法。

图 1. 通过 Web OAuth 在用户的手机上关联帐号

基于 OAuth 的应用快速关联 ('App Flip')

一个 OAuth 流程，可将用户转到应用以进行关联。

基于 OAuth 的应用快速关联可引导用户在经过验证的 Android 或 iOS 移动应用与 Google 平台之间移动，以查看提议的数据访问更改，并表示同意在您的平台上将其帐号与 Google 帐号关联。如需启用应用快速关联，您的服务必须支持使用授权代码流程的OAuth 链接或基于 OAuth 的 Google 登录链接。

Android 和 iOS 均支持应用快速关联。

运作方式：

Google 应用会检查您的应用是否已安装在用户的设备上：

• 如果找到相应应用，用户就会“翻转”到该应用。应用会征求用户的同意，以便将帐号与 Google 关联，然后再“翻转”到 Google 平台。
• 如果在应用快速关联过程中找不到应用或发生了错误，系统会将用户重定向到精简或 Web OAuth 流程。

图 2. 使用应用快速关联的用户手机上的帐号关联

基于 OAuth 的精简链接（精简）

基于 OAuth 的 Google 登录简化关联功能在 OAuth 关联功能的基础上添加了 Google 登录功能，让用户能够在不离开 Google 平台的情况下完成关联流程，从而减少摩擦和流失。基于 OAuth 的精简关联通过将 Google 登录与 OAuth 关联相结合，提供无缝登录、帐号创建和帐号关联方面的最佳用户体验。您的服务必须支持符合 OAuth 2.0 规范的授权和令牌交换端点。此外，您的令牌交换端点必须支持 JSON 网络令牌 (JWT) 断言，并实现 check、create 和 get intent。

注意：用户在此流程中从不会离开 Google 界面，因此 Google 必须代表第三方同意，才能让流程正常运行。

运作方式：

Google 会声明用户帐号并将以下信息传递给您：

• 如果数据库中已存在该用户的帐号，则该用户已成功将其 Google 帐号与其在服务上的帐号相关联。
• 如果数据库中不存在该用户的帐号，用户可以创建新的第三方帐号（使用 Google 提供的断言信息：电子邮件地址、姓名和个人资料照片），或者选择登录并使用其他电子邮件地址进行关联（这将要求他们通过 Web OAuth 登录服务）。

图 3. 通过简化的关联在用户的手机上关联帐号

您应该使用哪种流程？

我们建议实现所有流程，以确保用户获得最佳关联体验。精简流程和应用快速切换流程可以减少链接的不便，因为用户只需几步即可完成关联流程。网络 OAuth 关联操作的工作量最少，可以先尝试其他关联流程。

注意：所有集成都需要网络 OAuth 流程，因为它是其他流程的回退。

使用令牌

Google 帐号关联基于 OAuth 2.0 行业标准。

获得帐号持有人同意关联其帐号并分享数据后，您即可为各个 Google 帐号颁发访问令牌。

Token types

OAuth 2.0 uses strings called tokens to communicate between the user agent, the client application, and the OAuth 2.0 server.

Three types of OAuth 2.0 tokens can be used during account linking:

• Authorization code. A short-lived token that can be exchanged for an access and a refresh token. For security purposes, Google calls your authorization endpoint to obtain a single use or very short-lived code.

• Access token. A token that grants the bearer access to a resource. To limit exposure that could result from the loss of this token, it has a limited lifetime, usually expiring after an hour or so.

• Refresh token. A long-lived token that can be exchanged for a new access token when an access token expires. When your service integrates with Google, this token is exclusively stored and used by Google. Google calls your token exchange endpoint to exchange refresh tokens for access tokens, which are in turn used to access user data.

Token handling

Race conditions in clustered environments and client-server exchanges can result in complex timing and error handling scenarios when working with tokens. For example:

• You receive a request for a new access token, and you issue a new access token. Concurrently, you receive a request for access to your service's resource using the previous, unexpired access token.
• Your refresh token reply is yet to be received (or is never received) by Google. Meanwhile, the previously valid refresh token is used in a request from Google.

Requests and replies can arrive in any order, or not at all due to asynchronous services running in a cluster, network behavior, or other means.

Immediate and fully consistent shared state both within, and between, your and Google's token handling systems cannot be guaranteed. Multiple valid, unexpired tokens can coexist within or across systems short period of time. To minimize negative user impact we recommend you do the following:

• Accept unexpired access tokens, even after a newer token is issued.
• Use alternatives to Refresh Token Rotation.
• Support multiple, concurrently valid access and refresh tokens. For security, you should limit the number of tokens and token lifetime.

Maintenance and outage handling

During maintenance or unplanned outages Google might be unable to call your authorization or token exchange endpoints to obtain access and refresh tokens.

Your endpoints should respond with a 503 error code and empty body. In this case, Google retries failed token exchange requests for a limited time. Provided that Google is later able to obtain refresh and access tokens, failed requests are not visible to users.

Warning: Do not return a 400 error code and {"error": "invalid_grant"} body during maintenance or outages. Doing so deletes previously issued tokens and requires users to relink their accounts.

Failing requests for an access token result in a visible error, if initiated by a user. Users will be required to retry linking failures if the implicit OAuth 2.0 flow is used.

Recommendations

There are many solutions to minimize maintenance impact. Some options to consider:

• Maintain your existing service and route a limited number of requests to your newly updated service. Migrate all requests only after confirming expected functionality.

• Reduce the number of token requests during the maintenance period:

  • Limit maintenance periods to less than the access token lifetime.

  • Temporarily increase the access token lifetime:

    1. Increase token lifetime to greater than maintenance period.
    2. Wait twice the duration of your access token lifetime, enabling users to exchange short lived tokens for longer duration tokens.
    3. Enter maintenance.
    4. Respond to token requests with a 503 error code and empty body.
    5. Exit maintenance.
    6. Decrease token lifetime back to normal.

向 Google 注册

我们需要您的 OAuth 2.0 设置详情并共享凭据以启用帐号关联。如需了解详情，请参阅注册。