OAuth 关联概念指南

OAuth 关联类型支持两种业界标准 OAuth 2.0 流程：隐式流程和授权代码流程。在隐式代码流程中，Google 会在用户的浏览器中打开您的授权端点。登录成功后，您将向 Google 返回一个长期有效的访问令牌。然后，此访问令牌会包含在 Google 助理向您的 Action 发送的每个请求中。

如果您符合以下情况，则推荐使用 OAuth 关联解决方案：

• 您目前已有 OAuth 2.0 服务器实现，并且无法通过扩展令牌交换端点来添加对通过 ID 令牌自动关联和创建账号的 Google 协议的支持（即在向此端点的请求中添加 intent=get 和 intent=create 参数）。

如需验证 OAuth 关联是不是您的正确解决方案，请参阅选择帐号关联类型页面。

关键术语

在了解 OAuth 关联的工作原理之前，请先熟悉以下术语：

• user.verificationStatus：系统设置的一个属性，用于指示当前会话是否有经过验证的用户。

• user.accountLinkingStatus：系统设置的一个属性，用于指示当前会话中的用户是否具有关联的身份。

• 帐号关联系统场景：实现帐号关联确认流程的预定义场景，可自定义以适应特定用例。

• 授权代码流程：在此 OAuth 2.0 流程中，Google 会在用户的浏览器中打开您的授权端点。如果登录成功，您的服务会创建一个授权代码并将其返回给 Google。Google 会将此授权代码发送到您的令牌交换端点，该端点会验证代码的真实性并返回访问令牌和刷新令牌。

  此流程需要两个端点：

  • 授权端点：负责就数据访问征求用户意见或征得用户同意的端点。此端点执行以下操作：
    1. 向尚未登录的用户显示登录界面。
    2. 记录以短期授权代码的形式表示同意所请求的访问。
  • 令牌交换端点：此端点用于获取称为“令牌”的加密字符串，这些令牌可授权 Action 用户访问您的服务。此端点负责两种类型的交换：
    1. 将授权代码交换为长期刷新令牌和短期访问令牌。当用户完成帐号关联流程时，就会发生这种交换。
    2. 将长期刷新令牌交换为短期访问令牌。当 Google 因已过期的访问令牌而需要新的访问令牌时，就会发生这种交换。

• 隐式代码流程：在此 OAuth 2.0 流程中，Google 会在用户的浏览器中打开您的授权端点。如果登录成功，您将向 Google 返回一个长期有效的访问令牌。然后，此访问令牌会包含在 Google 助理向您的 Action 发送的每个请求中。此流程只需要一个授权端点。

• 访问令牌：用于授权服务访问用户部分数据的令牌。访问令牌与每个用户关联，并且应该无法猜测。

• 刷新令牌：在短期有效的访问令牌到期后用于交换新访问令牌的令牌。

运作方式

本部分介绍了 OAuth 授权代码的一般流程和隐式流程。以下 OAuth 关联流程部分介绍了 OAuth 可能执行的各种流程。

授权代码流程可总结如下：

1. 您的 Action 会询问用户是否希望将其账号与您的服务相关联。
2. 用户同意关联帐号后，Google 会在用户的浏览器中打开您的授权端点。如果针对 Action 的流程在仅支持语音的设备上启动，Google 会将执行转移到手机。
3. 用户登录（如果尚未登录），并授予 Google 使用您的 API 访问其数据的权限（如果他们尚未授予权限）。
4. 您的服务会创建授权代码，并将用户的浏览器重定向回 Google，并将授权代码附加到请求，从而将其返回给 Google。
5. Google 会将授权代码发送到您的令牌交换端点，该端点会验证代码的真实性并返回访问令牌和刷新令牌。访问令牌是短期有效的令牌，您的服务可接受该令牌作为访问 API 的凭据。刷新令牌是一个长期令牌，Google 可以存储该令牌，并在令牌过期时用它来获取新的访问令牌。
6. 用户完成帐号关联流程后，从 Google 助理发送到您的执行方式网络钩子的每个后续请求都会包含一个访问令牌。

隐式代码流程可总结如下：

1. 您的 Action 会询问用户是否要将其账号与您的服务相关联。
2. 用户同意关联帐号后，Google 会在用户的浏览器中打开您的授权端点。
3. 用户登录（如果尚未登录），并授予 Google 使用您的 API 访问其数据的权限（如果他们尚未授予权限）。
4. 您的服务会创建访问令牌，并将用户的浏览器连同请求附加的访问令牌重定向回 Google，从而将其返回给 Google。
5. 用户完成帐号关联流程后，Google 会调用您的服务的 API，并为每个请求附加访问令牌。您的服务会验证访问令牌是否授予 Google 访问 API 的授权，然后完成 API 调用。

基本授权代码流程如下所示：

1. 您的 Action 会询问用户是否希望将其账号与您的服务相关联。
2. 用户同意关联帐号后，Google 会在用户的浏览器中打开您的授权端点。如果针对 Action 的流程在仅支持语音的设备上启动，Google 会将执行转移到手机。
3. 用户登录（如果尚未登录），并授予 Google 使用您的 API 访问其数据的权限（如果他们尚未授予权限）。
4. 您的服务会创建授权代码，并将用户的浏览器重定向回 Google，并将短期授权代码附加到请求，从而将其返回给 Google。
5. Google 会将授权代码发送到您的令牌交换端点，该端点会验证代码的真实性并返回访问令牌和刷新令牌。访问令牌是短期有效的令牌，您的服务可接受该令牌作为访问 API 的凭据。刷新令牌是一个长期令牌，Google 可以存储该令牌，并在令牌过期时用它来获取新的访问令牌。
6. 用户完成帐号关联流程后，从 Google 助理发送到您的执行方式网络钩子的每个后续请求都会包含一个访问令牌。

OAuth 关联流程

本部分介绍了 OAuth 关联可能执行的各种流程。

注意 ：以下流程假定用户同意将其帐号与您的服务相关联，并授予 Google 使用您的 API 访问其数据的权限。如果用户不同意，请提供受限的备用流程，让用户能够继续在您的 Action 中继续操作。如需了解详情，请参阅最佳实践。

每个流程都包含用户调用您的 Action 后执行以下常见步骤：

注意 ：从 Webhook 到 User 的一行表示您创建和自定义的简单响应。从“Google 助理”到“用户”的线条表示由 Google 助理拥有且具有有限的自定义选项的提示（需要权限的请求始终归 Google 助理所有）。从用户的角度来看，这两种响应都是由 Google 助理传送的。

在上述流程中，您将过渡到帐号关联系统场景，并提供自定义理由。Google 助理会询问用户是否要将帐号与您的服务相关联，并向其显示包含所请求的权限的屏幕。如果用户同意，Google 随后会将用户重定向到浏览器中您的服务的授权端点。用户登录（或者根据您的配置创建新帐号），并向您的 Action 授予访问其数据的权限。

此后的流程因您是否实现了隐式流程或授权代码流程而有所不同。以下部分介绍了这些流程。

流程 1：用户通过隐式流程登录

注意 ：此图以上面的常见步骤图表为基础。

用户登录并验证其凭据后，您的服务会创建一个长期有效的访问令牌并将其返回给 Google。此时，用户在您的 Action 中的身份与用户登录时使用的帐号相关联，访问令牌将附加到 Google 对您服务的 API 发出的每个 API 调用。

流程 2：用户使用授权代码流程登录

注意 ：此图以上面的常见步骤图表为基础。

用户登录并验证其凭据后，您的服务会创建一个授权代码并将其返回给 Google。

此授权代码会发送到您的令牌交换端点，该端点会返回访问令牌和刷新令牌。此时，用户在您的 Action 中的身份与用户登录所用的任何帐号相关联，从 Google 助理发送到您的执行方式的每个后续请求都包含一个访问令牌。