OAuth 和 Google 登录概念指南 (Dialogflow)

OAuth 和 Google 登录关联类型会在基于 OAuth 的帐号关联基础上添加 Google 登录。如果您在 Action 中使用此关联类型,相应流程就会以 Google 登录开始,这样您可以检查系统中是否存在用户的 Google 个人资料信息。否则,系统会启动标准 OAuth 流程。通过提供这两种关联类型的组合,您的用户可以在您的 Action 中将其身份与 Google 帐号或非 Google 帐号相关联。他们也可以选择使用其 Google 个人资料信息创建新帐号。

如果存在以下任一情况,我们推荐使用 OAuth 和 Google 登录的帐号关联解决方案:

  • 您有一个跨多个平台运行的 Action(例如,如果您的 Action 适用于 Android 应用)。
  • 您已有一个身份验证系统,并且您希望允许用户将其身份与非 Google 帐号相关联。例如,如果您提供会员回馈活动,并希望确保用户不会失去其现有帐号中累积的积分。

如需验证 OAuth 和 Google 登录功能是否是适合您的解决方案,请参阅选择帐号关联类型页面。

关键术语

在了解 OAuth 和 Google 登录的工作原理之前,请先熟悉以下术语:

  • Google ID 令牌:一个已签名的用户身份断言,其中包含用户的基本 Google 个人资料信息(姓名、电子邮件地址和个人资料照片)。Google ID 令牌是 JSON 网络令牌 (JWT)。以下是已解码令牌的示例:
{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}
  • 帐号登录帮助程序 intent:您为了向 Google 助理请求帐号关联流程而调用的辅助 intent。如需了解详情,请参阅帐号登录
    • 上下文字符串:您添加到帐号登录帮助程序 intent 中的自定义字符串,用于告知用户您为何要关联其帐号。
  • 授权代码流程:您可以通过 OAuth + Google 登录实现的 OAuth 2.0 流程。此流程需要两个端点:
    • 授权端点:向尚未登录的用户显示登录界面的端点。它以短期授权代码的形式记录用户对请求的访问的同意情况。
    • 令牌交换端点:此端点负责两种交换:
      1. 将授权代码交换为长期刷新令牌和短期访问令牌。当用户完成帐号关联流程时,就会发生这种交换。
      2. 将长期刷新令牌交换为短期访问令牌。当 Google 因已过期的访问令牌而需要新的访问令牌时,就会发生这种交换。
  • 隐式代码流程:可通过 OAuth + Google 登录实现的 OAuth 2.0 流程。此流程只需要授权端点。在此过程中,Google 会在用户的浏览器中打开您的授权端点。如果登录成功,您将向 Google 返回一个长期有效的访问令牌。现在,从 Google 助理发送到您的 Action 的每个请求中都包含此访问令牌。
  • 访问令牌:用于授权您的服务访问用户部分数据的令牌。访问令牌与每个用户相关联。
  • 刷新令牌:在短期有效的访问令牌到期后用于交换新访问令牌的令牌。

前提条件

若要使用 OAuth 和 Google 登录关联类型,您需要具备以下条件:

  • OAuth 2 服务器
  • 令牌交换端点

    必须扩展令牌交换端点,以添加对从 ID 令牌自动关联和创建帐号的 Google 协议的支持(即在向此端点的请求中添加 intent=getintent=create 参数)。

运作方式

本部分介绍了 OAuth 和 Google 登录的一般流程。以下 OAuth 和 GSI 流程部分介绍了可能出现的各种流程,即:a) 是启用还是禁止通过语音创建帐号;b) 是使用隐式代码流程还是授权代码流程。

基本流程如下所示:

  1. 您的 Action 会请求用户同意访问其 Google 个人资料。
  2. 用户表示同意后,您的 Action 会收到一个包含用户的 Google 个人资料信息的 Google ID 令牌。
  3. 您必须验证并解码该令牌,才能读取配置文件内容。
  4. 您的 Action 会使用此令牌检查您的系统中是否存在用户的 Google 个人资料信息。
    1. 如果关联,则表示用户已使用其 Google 帐号登录您的系统,并且 Google 助理会将用户的身份与其 Google 帐号相关联。用户可以在关联帐号后继续与 Google 助理对话。
    2. 如果没有,请参阅第 5 步。
  5. 用户可以:a) 使用其 Google 个人资料信息创建新帐号,或 b) 使用其他帐号登录您的系统。用户看到的选项因您是否允许或禁止通过语音创建帐号而异。如果用户选择使用其他帐号登录您的系统,标准 OAuth 流程便会开始。
  6. 用户创建新帐号或使用其他提供方登录后,您的服务会向 Google 返回访问令牌。(如果您使用的是授权代码流程,您的服务也会返回一个刷新令牌)。
  7. 现在,用户可在关联帐号后继续与 Google 助理对话。

OAuth 和 GSI 流程

本部分介绍了 OAuth 和 GSI 可能执行的各种流程。 这些图表说明了授权代码流程(而不是隐式代码流程)发生的流程,并假设您使用 Dialogflow 作为 Action 的自然语言理解解决方案。

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

在上述流程中,您将使用自定义的上下文字符串调用 actions.intent.SIGN_IN 帮助程序 intent。此 intent 会请求用户授予访问其 Google 个人资料信息的权限。用户同意后,Google 助理会发送一个包含 user@gmail.com 个人资料信息的请求。

此后的流程取决于您是否配置了语音帐号关联以及您的系统中是否已存在用户的信息。以下各部分将分别介绍上述各个流程。

已启用语音账号创建功能的流

本部分详细介绍了启用通过语音创建帐号时可能执行的帐号关联流程。

流程 1:用户信息存在于您的系统中

在这种情况下,由 user@gmail.com 表示的用户存在于您的后端中,因此您的令牌交换端点为用户返回一个令牌。用户在您的 Action 中的身份现已与其 Google 帐号相关联。用户的原始请求 (“Order my normal”) 与自定义 intent 匹配order_drink. 然后,网络钩子会处理所匹配 intent 的执行方式,并向数据库查询 user@gmail.com 的常规顺序。然后,用户可以继续与 Google 助理对话。

流程 2:用户信息不存在,用户创建了账号

由于您通过语音启用了帐号创建功能,但您的后端中不存在 user@gmail.com,因此 Google 助理会询问用户是否想要执行以下任一操作:

a) 使用 Google 个人资料信息(通过语音完成)在你的系统上创建新帐号

b) 使用其他账号登录系统

在这种情况下,用户选择通过语音创建新帐号。Google 会通过创建帐号的请求来调用您的服务的令牌交换端点。此请求包含 Google ID 令牌,其中包括创建新帐号所需的组件。然后,您可以使用此令牌中的信息(用户的姓名和电子邮件地址)为用户创建帐号。

创建帐号后,您的服务将为新创建的帐号返回访问令牌和刷新令牌。您的 Action 中用户的身份现已与其 Google 帐号相关联。用户的原始请求(“我的常规请求”)与自定义 intent order_drink. 匹配。然后,webhook 会处理匹配的 intent 的执行,并在您的数据库中查询 user@gmail.com 的常规顺序,该顺序尚不存在,因为用户是新用户。然后,您的 Action 就可以询问用户想要点些什么。

流程 3:用户信息不存在,用户使用其他账号登录

您已通过语音启用了帐号创建功能,因此 Google 助理会询问用户是否想要执行以下任一操作:

a) 使用 Google 个人资料信息(通过语音完成)在你的系统上创建新帐号

b) 使用其他账号登录系统

在这种情况下,用户选择使用其他帐号登录,从而启动标准 OAuth 流程。如果流程在仅支持语音的设备上开始,Google 会将执行转移到手机。然后,Google 会在用户的浏览器中打开您的授权端点,并且,根据您的配置,用户可以选择:a) 使用不使用 Google 登录功能的现有帐号登录您的服务,还是使用 b) 使用其他提供方创建新帐号。如需详细了解 OAuth 流程,请参阅 OAuth 概念指南

验证用户凭据后,您的服务会向 Google 返回访问令牌和刷新令牌。您的 Action 中的用户身份现已关联至非 Google 账号。用户的原始请求(““订购我的常规”)与自定义 intent 匹配order_drink.您的网络钩子随后会处理匹配 intent 的执行,并向数据库中查询user@gmail.com的常规订单,但该订单尚不存在,因为用户是新用户。然后,您的 Action 就可以询问用户想要点些什么,或者请他们设置自己的常规订单。

停用语音账号创建流程

本部分详细介绍了停用通过语音创建帐号功能时可能执行的帐号关联流程。

流程 4:用户信息不存在

您没有启用通过语音创建帐号的功能,并且后端中不存在相应用户,因此标准 OAuth 流程开始了。Google 助理会在用户的浏览器中打开您的授权端点(如果该流程始于纯语音设备上,Google 会将执行过程传输到带有屏幕的设备)。用户可以选择 a) 使用其他提供方登录(如果他们已使用其他帐号注册您的服务),或者 b) 使用其他提供方创建新帐号。如需详细了解 OAuth 流程,请参阅 OAuth 概念指南

验证用户凭据后,您的服务会向 Google 返回访问令牌和刷新令牌。您的 Action 中的用户身份现已关联至非 Google 账号。用户的原始请求(““订购我的常规”)与自定义 intent 匹配order_drink.您的网络钩子随后会处理匹配 intent 的执行,并向数据库中查询user@gmail.com的常规订单,但该订单尚不存在,因为用户是新用户。然后,您的 Action 可以要求用户设置他们的常规顺序。