此页面由 Cloud Translation API 翻译。

关联的帐号登录

通过 Google 账号关联，Google 账号持有人可以快速、顺畅、安全地连接到您的服务并与 Google 分享数据。

“关联的帐号登录”功能可为已将 Google 帐号与您的服务相关联的用户启用一键登录 Google。这可提升用户的体验，因为他们只需点击一下即可登录，而无需重新输入用户名和密码。这还可以降低用户在您的服务中创建重复帐号的几率。

要求

要实现关联的账号登录功能，您必须满足以下要求：

您的 Google 帐号 OAuth 关联实现支持 OAuth 2.0 授权代码流程。您的 OAuth 实现必须包含以下端点：
- 授权端点来处理授权请求。
- 令牌端点，用于处理访问令牌和刷新令牌请求。
- userinfo 端点，可用于检索在关联帐号登录过程中向用户显示的已关联用户基本帐号信息。
您有一个 Android 应用。

运作方式

必备条件：用户之前已将其 Google 账号与您的服务账号相关联。

您可以在一键登录流程中选择显示关联的账号。
系统会向用户显示一键登录提示，并提供使用其关联帐号登录您的服务的选项。
如果用户选择继续使用关联的账号，Google 会向您的令牌端点发送请求以保存授权代码。该请求包含您的服务发放的用户访问令牌以及 Google 授权代码。
您可以使用 Google 授权代码来换取包含用户 Google 帐号相关信息的 Google ID 令牌。
流程结束后，您的应用也会收到一个 ID 令牌，并将该令牌与您的服务器收到的 ID 令牌中的用户标识符进行匹配，以便让用户登录您的应用。

关联账号登录。 — **图 1.**已关联的帐号登录流程。如果用户的设备上有多个已登录的帐号，则可能会看到帐号选择器，并且只有在选择关联的帐号时才会转到“已关联的帐号登录”视图。

在您的 Android 应用中实现关联的帐号登录

若要在您的 Android 应用中支持关联的账号登录功能，请按照 Android 实现指南中的说明操作。

处理来自 Google 的授权代码请求

Google 会向您的令牌端点发出 POST 请求，以保存授权代码，供您交换用户的 ID 令牌。该请求包含用户的访问令牌和 Google 提供的 OAuth2 授权代码。

在保存授权代码之前，您必须先验证是否向 Google 授予了访问令牌（以 client_id 标识）。

HTTP 请求

示例请求

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

code=GOOGLE_AUTHORIZATION_CODE
&grant_type=urn:ietf:params:oauth:grant-type:reciprocal
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&access_token=ACCESS_TOKEN

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

令牌端点参数
`code`	必填 Google OAuth2 授权代码
`client_id`	您提供给 Google 的必需客户端 ID
`client_secret`	您发送给 Google 的必需客户端密钥
`access_token`	必需您发送给 Google 的访问令牌。您将用它来获取用户的上下文
`grant_type`	必填值必须设置为 `urn:ietf:params:oauth:grant-type:reciprocal`

您的令牌交换端点应通过执行以下操作来响应 POST 请求：

验证 access_token 已授予由 client_id 标识的 Google。
如果请求有效且授权代码成功交换为 Google ID 令牌，则返回 HTTP 200 (OK) 响应；如果请求无效，则返回 HTTP 错误代码。

HTTP 响应

成功

返回 HTTP 状态代码 200 OK

成功响应示例

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{}

错误

如果 HTTP 请求无效，请使用下列 HTTP 错误代码之一进行响应：

HTTP 状态代码	正文	说明
400	`{"error": "invalid_request"}`	该请求缺少参数，因此服务器无法继续处理该请求。如果请求包含不受支持的参数或重复参数，也有可能返回此错误
401	`{"error": "invalid_request"}`	客户端身份验证失败，例如请求中包含无效的客户端 ID 或密钥
401	`{"error": "invalid_token"}` 在响应标头中添加“WWW-Authentication: Bearer”身份验证质询	合作伙伴访问令牌无效。
403	`{"error": "insufficient_permission"}` 在响应标头中添加“WWW-Authentication: Bearer”身份验证质询	合作伙伴访问令牌未包含执行双向 OAuth 所需的范围
500	`{"error": "internal_error"}`	服务器错误

错误响应应包含以下字段：

错误响应字段
`error`	必填错误字符串
`error_description`	直观易懂的错误说明
`error_uri`	提供关于错误的更多详细信息的 URI

错误 400 响应示例

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error": "invalid_request",
  "error_description": "Request was missing the 'access_token' parameter."
}

交换 ID 令牌的授权代码

您需要将收到的授权代码换成一个包含用户 Google 帐号相关信息的 Google ID 令牌。

如需将授权代码换成 Google ID 令牌，请调用 https://oauth2.googleapis.com/token 端点并设置以下参数：

请求字段
`client_id`	必填。从 API 控制台的“凭据”页面中获取的客户端 ID。这通常是名为 New Actions on Google App 的凭据
`client_secret`	必填。从 API 控制台的“凭据”页面中获取的客户端密钥
`code`	必填。初始请求中发送的授权代码
`grant_type`	必填如 OAuth 2.0 规范中所定义，此字段的值必须设置为 `authorization_code`。

示例请求

POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=GOOGLE_AUTHORIZATION_CODE
&grant_type=authorization_code
&client_id=GOOGLE_CLIENT_ID
&client_secret=GOOGLE_CLIENT_SECRET

Google 通过返回包含短期有效访问令牌和刷新令牌的 JSON 对象响应此请求。

响应包含以下字段：

响应字段
`access_token`	您的应用发送的 Google 签发的访问令牌，用于授权 Google API 请求
`id_token`	ID 令牌包含用户的 Google 帐号信息。“验证响应”部分包含有关如何解码和验证 ID 令牌响应的详细信息
`expires_in`	访问令牌的剩余生命周期（以秒为单位）
`refresh_token`	可用于获取新访问令牌的令牌。刷新令牌在用户撤消访问权限之前一直有效
`scope`	对于“已关联的帐号登录”用例，此字段的值始终设为 openid
`token_type`	返回的令牌的类型。目前，此字段的值始终设置为 `Bearer`

响应示例

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8

{
  "access_token": "Google-access-token",
  "id_token": "Google-ID-token",
  "expires_in": 3599,
  "token_type": "Bearer",
  "scope": "openid",
  "refresh_token": "Google-refresh-token"
}


POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=Google authorization code
&grant_type=authorization_code
&client_id=Google client id
&client_secret=Google client secret

验证 ID 令牌响应

验证和解码 JWT 断言

您可以使用适用于您所用语言的 JWT 解码库。使用 Google 的公钥，在 JWK 或 PEM 格式，用于验证令牌的签名。

解码后，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": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

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

使用 email、email_verified 和 hd 字段，您可以确定 Google 负责托管电子邮件地址，并对其具有权威性。如果 Google 权威性 - 用户当前被认定为合法账号所有者您可以跳过密码或其他验证方法。否则，这些方法可用于在关联之前验证账号。

Google 具有权威性的情形：

email 的后缀为 @gmail.com，这是一个 Gmail 账号。
email_verified 为 true 且 hd 已设置，这是 G Suite 账号。

用户无需使用 Gmail 或 G Suite 即可注册 Google 账号。时间 email 不包含 @gmail.com 后缀，且 hd 不存在 Google 不建议使用权威凭据和密码或其他验证方法进行验证用户。email_verified 可能为 true，因为 Google 最初验证了创建 Google 账号后，该用户会获得第三方的所有权，后，电子邮件账号可能已更改。