通过 OAuth 和“使用 Google 账号登录”简化关联流程

概览

基于 OAuth 的“使用 Google 账号登录”简化版关联在 OAuth 关联的基础上添加了“使用 Google 账号登录”。这样一来，Google 用户便可顺畅地关联账号，同时还能创建账号，让用户可以使用自己的 Google 账号在您的服务中创建新账号。

如需使用 OAuth 和“使用 Google 账号登录”功能执行账号关联，请按以下常规步骤操作：

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

在用户手机上通过精简关联功能关联账号

图 1. 在用户手机上使用精简的关联方式进行账号关联

简化的关联：OAuth +“使用 Google 账号登录”流程

以下序列图详细说明了用户、Google 和您的令牌交换端点之间针对简化关联的互动。

图 2. 简化版关联流程中的事件序列。

角色和职责

下表定义了简化版关联流程中各个参与者的角色和职责。

执行者 / 组件	GAL 角色	职责
Google 应用 / 服务器	OAuth 客户端	获取用户对“使用 Google 账号登录”的同意情况，将身份断言 (JWT) 传递给您的服务器，并安全地存储生成的令牌。
您的令牌交换端点	身份提供方 / 授权服务器	验证身份断言，检查是否存在现有账号，处理账号关联 intent（check、get、create），并根据请求的 intent 签发令牌。
您的服务 API	资源服务器	在提供有效的访问令牌时，提供对用户数据的访问权限。

简化版关联的要求

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

注意： 这些 intent 必须在您为基本 OAuth 关联流程创建的同一令牌交换端点中实现。请勿创建其他端点来处理这些 intent。

• 注册您的 Google API 客户端 ID。

简化关联的决策逻辑

以下逻辑决定了在简化的关联流程中如何调用 intent：

1. 用户在您的身份验证系统中是否有账号？（用户通过选择“是”或“否”来决定）
   1. 是：用户是否使用与 Google 账号关联的电子邮件地址登录您的平台？（用户通过选择“是”或“否”来决定）
      1. 是：用户在您的身份验证系统中是否有匹配的账号？（调用 check intent 以进行确认）
         1. YES：调用 get intent，如果获取 intent 成功返回，则关联账号。
         2. 否：创建新账号？（用户通过选择“是”或“否”来决定）
            1. 是：调用 create intent，如果创建 intent 成功返回，则关联账号。
            2. 否：系统会触发 OAuth 关联流程，将用户定向到其浏览器，并为用户提供与其他电子邮件地址关联的选项。
      2. 否：系统会触发 OAuth 关联流程，将用户定向到其浏览器，并让用户选择是否关联其他电子邮件地址。
   2. 否：用户在您的身份验证系统中是否有匹配的账号？（调用 check intent 以进行确认）
      1. YES：调用 get intent，如果获取 intent 成功返回，则关联账号。
      2. 否：如果创建 intent 成功返回，则会调用 create intent 并关联账号。

实施方案

您的令牌交换端点必须实现 check、get 和 create intent，才能支持精简关联。

请按照以下步骤处理不同的 intent：

检查现有用户账号（检查 intent）

Google 会调用您的令牌交换端点，以验证 Google 用户是否存在于您的系统中。如需了解参数详情，请参阅简化的关联 intent。

实现方案

如需处理 check intent，请执行以下操作：

1. 验证请求：

   • 验证 client_id、client_secret 和 grant_type（必须为 urn:ietf:params:oauth:grant-type:jwt-bearer）。
   • 使用 JWT 验证 中的条件验证 assertion (JWT)。

2. 查找用户：

   • 检查 JWT 中的 Google 账号 ID (sub) 或电子邮件地址是否与数据库中的用户匹配。

3. 回应：

   • 如果找到：返回 HTTP 200 OK，并附带 {"account_found": "true"}。
   • 如果未找到：返回 HTTP 404 Not Found，并附带 {"account_found": "false"}。

Handle automatic linking (get intent)

If the account exists, Google calls your endpoint with intent=get to retrieve tokens. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the get intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Lookup user:

   • Verify the user exists using the sub or email claim.

3. Respond:

   • If successful: Generate and return access_token, refresh_token, and expires_in in a JSON response (HTTP 200 OK).
   • If linking fails: Return HTTP 401 Unauthorized with {"error": "linking_error"} and an optional login_hint to fall back to standard OAuth linking.

Handle account creation using Sign in with Google (create intent)

If no account exists, Google calls your endpoint with intent=create to create a new user. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the create intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Verify user does not exist:

   • Check if the sub or email is already in your database.
   • If the user does exist: Return HTTP 401 Unauthorized with {"error": "linking_error", "login_hint": "USER_EMAIL"} to force fallback to OAuth linking.

3. Create account:

   • Use the sub, email, name, and picture claims from the JWT to create a new user record.

4. Respond:

   • Generate and return tokens in a JSON response (HTTP 200 OK).

获取 Google API 客户端 ID

在账号关联注册过程中，您需要提供 Google API 客户端 ID。使用您在完成 OAuth 关联步骤时创建的项目获取 API 客户端 ID。为此，请完成以下步骤：

1. 前往“客户”页面。

2. 创建或选择 Google APIs 项目。

   如果您的项目没有 Web 应用类型的客户端 ID，请点击创建客户端进行创建。请务必在已获授权的 JavaScript 来源框中添加您网站的域名。在执行本地测试或开发时，您必须将 http://localhost 和 http://localhost:<port_number> 都添加到已获授权的 JavaScript 来源字段中。

   要点： 对于本地测试或开发，请将 http://localhost 和 http://localhost:<port_number> 同时添加到已获授权的 JavaScript 来源字段。

   注意：客户端 ID 类似于以下示例：

   1234567890-abc123def456.apps.googleusercontent.com
   

验证您的实现效果

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.