此页面由 Cloud Translation API 翻译。

通过 OAuth 和 Google 登录功能简化关联流程

概览

基于 OAuth 的 Google 登录简化关联功能会在 OAuth 关联。这样可以为 Google 用户），它还支持账号创建功能，即允许用户使用其 Google 账号在您的服务中创建新账号。

如需通过 OAuth 和 Google 登录机制执行账号关联，请遵循以下常规步骤：

首先，请用户同意访问其 Google 个人资料。
使用用户个人资料中的信息检查用户账号是否存在。
对于现有用户，请关联账号。
如果您在身份验证系统中找不到与 Google 用户匹配的信息，验证从 Google 收到的 ID 令牌。然后，您可以根据对 ID 令牌中包含的个人资料信息有效。

此图显示了用户使用简化的关联流程关联 Google 账号的步骤。第一个屏幕截图显示了用户如何选择要关联的应用。第二个屏幕截图可让用户确认他们是否已在您的服务中拥有账号。通过第三个屏幕截图，用户可以选择要关联的 Google 账号。第四个屏幕截图显示了将用户的 Google 账号与您的应用相关联的确认信息。第五个屏幕截图显示 Google 应用中已成功关联的用户账号。

图 1. 通过“精简关联”功能在用户手机上进行账号关联

简化关联的要求

实现基本网络 OAuth 关联流程。您的服务必须支持符合 OAuth 2.0 规定授权端点和令牌交换端点。
您的令牌交换端点必须支持 JSON 网络令牌 (JWT) 断言，并实现 check、create 和 get intent。

。

注册您的 Google API 客户端 ID。

实现 OAuth 服务器

您的令牌交换端点必须支持 check、create、get intent。下面显示了通过账号关联流程完成的步骤，并指明了不同 intent 的调用时间：

用户在您的身份验证系统中是否有账号？（用户可通过选择“是”或“否”来决定） <ph type="x-smartling-placeholder">
1. 是：用户是否使用与其 Google 账号关联的电子邮件地址登录您的平台？（用户可通过选择“是”或“否”来决定） <ph type="x-smartling-placeholder">
  1. 是：用户在您的身份验证系统中是否拥有匹配的账号？（系统会调用 check intent 来进行确认）
    1. 是：如果成功返回 get intent，系统会调用 get intent 并关联账号。
    2. 否：要创建新账号吗？（用户可通过选择“是”或“否”来决定） <ph type="x-smartling-placeholder">
      1. 是：如果成功返回 create intent，系统会调用 create intent 并关联账号。
      2. 否：会触发网络 OAuth 流程，将用户定向到其浏览器，并为用户提供链接到其他电子邮件的选项。
  2. 否：触发网络 OAuth 流程，将用户定向到其浏览器，并为用户提供用于链接到其他电子邮件的选项。
2. 否：用户在您的身份验证系统中是否拥有匹配的账号？（系统会调用 check intent 来进行确认）
  1. 是：如果成功返回 get intent，系统会调用 get intent 并关联账号。
  2. 否：如果成功返回 create intent，系统会调用 create intent 并关联账号。

Check for an existing user account (check intent)

After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.

If the corresponding Google account is already present in your authentication system, your token exchange endpoint responds with account_found=true. If the Google account doesn't match an existing user, your token exchange endpoint returns an HTTP 404 Not Found error with account_found=false.

The request has the following form:

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

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

Your token exchange endpoint must be able to handle the following parameters:

Token endpoint parameters
`intent`	For these requests, the value of this parameter is `check`.
`grant_type`	The type of token being exchanged. For these requests, this parameter has the value `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
`client_id`	The client ID you assigned to Google.
`client_secret`	The client secret you assigned to Google.

To respond to the check intent requests, your token exchange endpoint must perform the following steps:

Validate and decode the JWT assertion.
Check if the Google account is already present in your authentication system.

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

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_verified 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.

Check if the Google account is already present in your authentication system

Check whether either of the following conditions are true:

The Google Account ID, found in the assertion's sub field, is in your user database.
The email address in the assertion matches a user in your user database.

If either condition is true, the user has already signed up. In that case, return a response like the following:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

If neither the Google Account ID nor the email address specified in the assertion matches a user in your database, the user hasn't signed up yet. In this case, your token exchange endpoint needs to reply with a HTTP 404 error that specifies "account_found": "false", as in the following example:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

Handle automatic linking (get intent)

If the corresponding Google Account is already present in your authentication system, your token exchange endpoint returns a token for the user. If the Google Account doesn't match an existing user, your token exchange endpoint returns a linking_error error and optional login_hint.

The request has the following form:

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

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

Your token exchange endpoint must be able to handle the following parameters:

Token endpoint parameters
`intent`	For these requests, the value of this parameter is `get`.
`grant_type`	The type of token being exchanged. For these requests, this parameter has the value `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
`scope`	Optional: Any scopes that you've configured Google to request from users.
`client_id`	The client ID you assigned to Google.
`client_secret`	The client secret you assigned to Google.

To respond to the get intent requests, your token exchange endpoint must perform the following steps:

Validate and decode the JWT assertion.
Check if the Google account is already present in your authentication system.

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

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.

Check if the Google account is already present in your authentication system

Check whether either of the following conditions are true:

The Google Account ID, found in the assertion's sub field, is in your user database.
The email address in the assertion matches a user in your user database.

If an account is found for the user, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

In some cases, account linking based on ID token might fail for the user. If it does so for any reason, your token exchange endpoint needs to reply with a HTTP 401 error that specifies error=linking_error, as the following example shows:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

When Google receives a 401 error response with linking_error, Google sends the user to your authorization endpoint with login_hint as a parameter. The user completes account linking using the OAuth linking flow in their browser.

Handle account creation via Google Sign-In (create intent)

When a user needs to create an account on your service, Google makes a request to your token exchange endpoint that specifies intent=create.

The request has the following form:

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

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

Your token exchange endpoint must able to handle the following parameters:

Token endpoint parameters
`intent`	For these requests, the value of this parameter is `create`.
`grant_type`	The type of token being exchanged. For these requests, this parameter has the value `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
`client_id`	The client ID you assigned to Google.
`client_secret`	The client secret you assigned to Google.

The JWT within the assertion parameter contains the user's Google Account ID, name, and email address, which you can use to create a new account on your service.

To respond to the create intent requests, your token exchange endpoint must perform the following steps:

Validate and decode the JWT assertion.
Validate user information and create new account.

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

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.

Validate user information and create new account

Check whether either of the following conditions are true:

The Google Account ID, found in the assertion's sub field, is in your user database.
The email address in the assertion matches a user in your user database.

If either condition is true, prompt the user to link their existing account with their Google Account. To do so, respond to the request with an HTTP 401 error that specifies error=linking_error and gives the user's email address as the login_hint. The following is a sample response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

If neither condition is true, create a new user account with the information provided in the JWT. New accounts don't typically have a password set. It's recommended that you add Google Sign-In to other platforms to enable users to log in with Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password to sign in on other platforms.

When the creation is completed, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

获取您的 Google API 客户端 ID

在账号关联注册过程中，系统会要求您提供 Google API 客户端 ID。

使用您在完成 OAuth 关联步骤时创建的项目获取 API 客户端 ID。为此，请完成以下步骤：

打开凭据页面 Google API 控制台。
创建或选择 Google API 项目。

如果您的项目没有 Web 应用类型的客户端 ID，请点击 创建凭据 >OAuth 客户端 ID 创建一个凭据。请确保包含在已获授权的 JavaScript 来源框中，输入您网站的网域。当您执行本地测试或开发，则必须同时添加 http://localhost 和 http://localhost:<port_number> 添加到已获授权的 JavaScript 来源字段中。

要点：同时添加 http://localhost 和 http://localhost:<port_number> 输入已获授权的 JavaScript 来源字段以进行本地测试，或开发。
注意：客户端 ID 如以下示例所示：
```
1234567890-abc123def456.apps.googleusercontent.com
```

验证您的实现

您可以通过使用验证实现的OAuth 2.0游乐场工具。

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

单击配置打开的OAuth 2.0配置窗口。
在OAuth流场中，选择客户端。
在OAuth端点字段中，选择自定义。
在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
在步骤1部分，不要选择任何谷歌范围。相反，将此字段留空或键入对您的服务器有效的范围（如果不使用 OAuth 范围，则输入任意字符串）。当您完成后，单击授权的API。
在步骤2和步骤3段，完成OAuth 2.0流程和验证每个步骤按预期工作。

您可以通过验证您的实现谷歌帐户链接演示工具。

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

点击登录在与谷歌按钮。
选择您要关联的帐户。
输入服务标识。
（可选）输入您将请求访问的一个或多个范围。
单击开始演示。
出现提示时，确认您可以同意并拒绝链接请求。
确认您被重定向到您的平台。