通过 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：

Check for an existing user account (check intent)

Google calls your token exchange endpoint to verify if the Google user exists in your system. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the check intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type (must be urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Validate the assertion (JWT) using the criteria in JWT Validation.

2. Lookup user:

   • Check if the Google Account ID (sub) or email address in the JWT matches a user in your database.

3. Respond:

   • If found: Return HTTP 200 OK with {"account_found": "true"}.
   • If not found: Return HTTP 404 Not Found with {"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.

使用“使用 Google 账号登录”功能处理账号创建事宜（创建 intent）

如果不存在任何账号，Google 会使用 intent=create 调用您的端点，以创建新用户。如需了解参数详情，请参阅 Streamlined Linking Intents。

实现方案

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

1. 验证请求：

   • 验证 client_id、client_secret 和 grant_type。
   • 验证 assertion (JWT)。

2. 验证用户不存在：

   • 检查您的数据库中是否已存在 sub 或 email。
   • 如果用户 存在，请返回 HTTP 401 Unauthorized，并使用 {"error": "linking_error", "login_hint": "USER_EMAIL"} 强制回退到 OAuth 关联。

3. 创建账号：

   • 使用 JWT 中的 sub、email、name 和 picture 声明创建新的用户记录。

4. 回应：

   • 在 JSON 响应 (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
   

验证您的实现效果

您可以使用 OAuth 2.0 Playground 工具验证您的实现。

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

1. 点击配置 以打开“OAuth 2.0 配置”窗口。
2. 在 OAuth flow（OAuth 流程）字段中，选择 Client-side（客户端）。
3. 在 OAuth Endpoints 字段中，选择 Custom。
4. 在相应字段中指定您的 OAuth 2.0 端点以及您分配给 Google 的客户端 ID。
5. 在第 1 步部分中，请勿选择任何 Google 范围。请将此字段留空，或输入适用于您服务器的范围（如果您不使用 OAuth 范围，则输入任意字符串）。完成后，点击 Authorize APIs。
6. 在第 2 步和第 3 步部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示工具验证您的实现。

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

1. 点击使用 Google 账号登录按钮。
2. 选择您要关联的账号。
3. 输入服务 ID。
4. （可选）输入您将请求访问的一个或多个范围。
5. 点击开始演示。
6. 当系统提示时，请确认您可以同意或拒绝关联请求。
7. 确认您已重定向到相应平台。