关联的帐号登录

注意：Android 版一键快捷功能已废弃。为确保您的应用持续的安全性和易用性，请迁移到 Credential Manager。Credential Manager 支持通行密钥、密码和联合身份身份验证（例如“使用 Google 账号登录”），安全性更高，用户体验更一致。

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

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

注意 ：已关联的帐号登录功能仅适用于 Android。

要求

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

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

运作方式

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

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

注意 ：第 3 步和第 4 步是在用户首次尝试使用关联的账号登录时完成的。后续使用同一帐号登录时，系统会跳过这些步骤。

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

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

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

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

注意 ：您必须先向 Google 注册 OAuth2 端点，然后才能继续执行下面的步骤。

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

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

注意 ：这需要更新您的令牌端点。在 Google 帐号关联 OAuth 令牌请求中，Google 会调用您的令牌端点，用您提供的授权代码来换取访问令牌或刷新令牌。在“已关联的帐号登录令牌”请求中，Google 会调用您的令牌端点以保存授权代码。

令牌端点参数
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 令牌响应

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.

When decoded, the JWT assertion looks like the following example:

{
  "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
  "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
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com, that the audience (aud field) is your assigned client ID, and that the token has not expired (exp field).

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner and you may skip password or other challenges methods. Otherwise, these methods can be used to verify the account prior to linking.

Cases where Google is authoritative:

• email has a @gmail.com suffix, this is a Gmail account.
• email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verfied can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.