通过 OAuth 和 Google 登录 (Dialogflow) 实现帐号关联

OAuth 和 Google 登录关联类型会在基于 OAuth 的基础上添加 Google 登录 账号关联。这样可以为 Google 用户提供基于语音的无缝链接 还可以为注册您服务的用户启用账号关联 使用非 Google 身份创建。

这种关联类型从 Google 登录开始，这样您就可以查看用户是否 您的系统中已存在 Google 个人资料信息。如果用户的信息 ，则开始标准 OAuth 流程。用户还可以 选择用其 Google 个人资料信息创建一个新账号。

<ph type="x-smartling-placeholder">

</ph>

图 1：您的 Action 可以访问用户的 Google 个人资料，您可以使用它在您的身份验证系统中查找与该用户匹配的账号。

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

1. 首先，请用户同意访问其 Google 个人资料。
2. 使用用户个人资料中的信息来识别用户。
3. 如果您在身份验证系统中找不到与 Google 用户匹配的信息， 流程是否继续取决于您是否配置了 Actions 项目 在 Actions 控制台中，允许用户通过语音创建用户账号，或仅允许 。
   • 如果您允许通过语音创建账号，请验证身份证件 从 Google 收到的令牌。然后，您可以根据 个人资料信息。
   • 如果您不允许通过语音创建账号，则系统会将用户转到 一个浏览器，他们可以加载您的授权页面， 创建流程

图 2. OAuth 和 Google 在您的系统中找不到用户信息时的登录流程。

支持通过语音创建账号

如果您允许通过语音创建用户账号，Google 助理会询问用户 他们希望执行以下操作：

• 使用对方的 Google 账号信息在您的系统上创建新账号，或者
• 使用已有其他账号登录您的身份验证系统 现有的非 Google 账号。

如果您希望尽量减少 账号创建流程中的障碍用户只需退出语音流 可以使用现有的非 Google 账号登录。

禁止通过语音创建账号

如果你禁止通过语音创建用户账号，Google 助理会打开 您为用户身份验证而提供的网站。如果互动发生 在没有屏幕的设备上，Google 助理会将用户转到手机 以继续进行账号关联流程。

在以下情况下，建议禁止创建：

• 您不希望允许拥有非 Google 账号的用户创建新的 用户账号，并希望将用户与您账号中的 身份验证系统。例如，如果您提供会员回馈活动， 可能需要确保用户不会丢失其 现有账号

• 您需要完全控制账号创建流程。例如，你可以 禁止创建（如果您需要向用户显示服务条款） 创建账号。

。

注意： 请选择下方的某个流程选项，详细了解如何实现 所选流。如有需要，指南内容将会重新加载以适应 内容。

<ph type="x-smartling-placeholder"></ph> 允许通过语音创建账号 禁止通过语音创建账号

实现 OAuth 和 Google 登录账号关联

账号已与业界标准的 OAuth 2.0 流程相关联。 Actions on Google 支持隐式和授权代码流程。

注意 ：如果您要实现账号关联以处理财务信息， 请注意，你的 Action 可能需要遵守其他政策。我们最多可等待 6 个项目 有数周时间查看包含账号关联的 Action，以便获取财务信息， 在规划发布时间表时，会将这个时间考虑在内。简化审核 流程，请确保您遵守金融服务政策 然后再提交 Action 以供审核。

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

Note: Please choose which OAuth2 flow you want to implement. If needed, the content of this guide reloads to adapt to your choice.

Auth code Implicit flow

配置项目

将项目配置为使用 OAuth 和 Google 登录账号 请按照以下步骤进行操作：

1. 打开 Actions 控制台，然后选择要使用的项目。
2. 点击开发标签页，然后选择账号关联。
3. 启用账号关联旁边的开关。
4. 在“账号创建”部分，选择是。

5. 在关联类型中，选择 OAuth & OAuth &Google 登录和隐式。

   

6. 在客户端信息中，执行以下操作：

   • 为 Actions to Google 颁发的客户端 ID 指定一个值，以标识 来自 Google 的请求
   • 插入授权端点和令牌交换端点的网址。

7. 点击保存。

实现 OAuth 服务器

To support the OAuth 2.0 implicit flow, your service makes an authorization endpoint available by HTTPS. This endpoint is responsible for authenticating and obtaining consent from users for data access. The authorization endpoint presents a sign-in UI to your users that aren't already signed in and records consent to the requested access.

When your Action needs to call one of your service's authorized APIs, Google uses this endpoint to get permission from your users to call these APIs on their behalf.

A typical OAuth 2.0 implicit flow session initiated by Google has the following flow:

1. Google opens your authorization endpoint in the user's browser. The user signs in if not signed in already, and grants Google permission to access their data with your API if they haven't already granted permission.
2. Your service creates an access token and returns it to Google by redirecting the user's browser back to Google with the access token attached to the request.
3. Google calls your service's APIs, and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.

Handle authorization requests

When your Action needs to perform account linking via an OAuth2 implicit flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

Authorization endpoint parameters
client_id	The client ID you assigned to Google.
redirect_uri	The URL to which you send the response to this request.
state	A bookkeeping value that is passed back to Google unchanged in the redirect URI.
response_type	The type of value to return in the response. For the OAuth 2.0 implicit flow, the response type is always token.

For example, if your authorization endpoint is available at https://myservice.example.com/auth, a request might look like:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

For your authorization endpoint to handle sign-in requests, do the following steps:

1. Verify the client_id and redirect_uri values to prevent granting access to unintended or misconfigured client apps:

   • Confirm that the client_id matches the client ID you assigned to Google.
   • Confirm that the URL specified by the redirect_uri parameter has the following form:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID is the ID found on the Project settings page of the Actions Console.

2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.

3. Generate an access token that Google will use to access your API. The access token can be any string value, but it must uniquely represent the user and the client the token is for and must not be guessable.

4. Send an HTTP response that redirects the user's browser to the URL specified by the redirect_uri parameter. Include all of the following parameters in the URL fragment:

   • access_token: the access token you just generated
   • token_type: the string bearer
   • state: the unmodified state value from the original request The following is an example of the resulting URL:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google's OAuth 2.0 redirect handler will receive the access token and confirm that the state value hasn't changed. After Google has obtained an access token for your service, Google will attach the token to subsequent calls to your Action as part of the AppRequest.

处理自动关联

在用户同意你的 Action 访问他们的 Google 个人资料后，Google 发送请求，其中包含 Google 用户身份的已签名断言。 该断言包含的信息包括用户的 Google 账号 ID、姓名、 和电子邮件地址。为项目配置的令牌交换端点处理 请求。

如果您的身份验证系统中已经存在相应的 Google 账号， 您的令牌交换端点为用户返回令牌。如果 Google 账号没有 匹配现有用户，您的令牌交换端点会返回 user_not_found 错误。

请求的格式如下：

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&consent_code=CONSENT_CODE&scope=SCOPES

您的令牌交换端点必须能够处理以下参数：

令牌端点参数
grant_type	所交换的令牌的类型。对于这类请求 参数的值为 urn:ietf:params:oauth:grant-type:jwt-bearer。
intent	对于这些请求，此参数的值为 `get`。
assertion	一个 JSON Web 令牌 (JWT)，提供 Google 用户身份。JWT 包含的信息包括 账号 ID、名称和电子邮件地址。
consent_code	可选：一个一次性代码（如果存在）用于表明 用户已同意你的 Action 访问指定范围。
scope	可选：您配置 Google 向用户请求的任何范围。

当您的令牌交换端点收到关联请求时，它应该 以下：

验证和解码 JWT 断言

您可以使用适用于您语言的 JWT 解码库来验证和解码 JWT 断言。 使用 Google 的公钥（适用于 JWK 或 PEM 格式）来验证令牌的 签名。

注意 ：不得对键进行硬编码。而应按照 OpenID Connect Discovery 协议 并检查 cache-control 标头，以确定应将密钥缓存多长时间。

解码后，JWT 断言如以下示例所示：

{
  "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": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

除了验证令牌的签名之外，还要验证断言的颁发者 （iss 字段）为 https://accounts.google.com，且受众群体（aud 字段） 是分配给您的 Action 的客户端 ID。

检查您的身份验证系统中是否已存在该 Google 账号

请检查以下任一条件是否成立：

• Google 账号 ID 可在断言的 sub 字段中找到，也可位于您的用户数据库中。
• 断言中的电子邮件地址与用户数据库中的用户匹配。

如果满足上述任一条件，则表明用户已经注册，您可以发出 访问令牌。

如果断言中指定的 Google 账号 ID 和电子邮件地址都没有 与您数据库中的用户匹配，表示该用户尚未注册。在这种情况下，您的 令牌交换端点应回复 HTTP 401 错误，指定 error=user_not_found， 如以下示例中所示：

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

{
  "error":"user_not_found",
}

当 Google 收到包含 user_not_found 错误的 401 错误响应时， 使用 intent 参数的值调用您的令牌交换端点 设置为 create 并发送包含用户个人资料信息的 ID 令牌 一起发送。

Handle account creation via Google Sign-In

When a user needs to create an account on your service, Google makes a request to your token exchange endpoint that specifies intent=create, as in the following example:

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&consent_code=CONSENT_CODE&assertion=JWT[&NEW_ACCOUNT_INFO]

The assertion parameter contains 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, which you can use to create a new account on your service.

To respond to account creation requests, your token exchange endpoint must do the following:

验证和解码 JWT 断言

您可以使用适用于您语言的 JWT 解码库来验证和解码 JWT 断言。 使用 Google 的公钥（适用于 JWK 或 PEM 格式）来验证令牌的 签名。

注意 ：不得对键进行硬编码。而应按照 OpenID Connect Discovery 协议 并检查 cache-control 标头，以确定应将密钥缓存多长时间。

解码后，JWT 断言如以下示例所示：

{
  "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": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

除了验证令牌的签名之外，还要验证断言的颁发者 （iss 字段）为 https://accounts.google.com，且受众群体（aud 字段） 是分配给您的 Action 的客户端 ID。

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 by responding to the request with an HTTP 401 error, specifying error=linking_error and the user's email address as the login_hint, as in the following example:

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

{
  "error":"linking_error",
  "login_hint":"[e-mail]"
}

If neither condition is true, create a new user account using the information provided in the JWT. New accounts do not typically have a password set. It is recommended that you add Google Sign In to other platforms to enable users to log in via 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 for signing 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
}

启动身份验证流程

警告：请勿向用户提供必需的账号 关联提示。相反， 为未经身份验证的用户提供访客流程，以展示您的 Action 的运作方式； 则仅在必要时要求进行账号关联以继续操作。如果用户 导致 Action 因账号关联问题而持续存在，Google 将 未主动宣传该 Action，这可能会导致该 Action 的用户流量减少。

请注意，只有经过验证的用户才能执行账号关联。如果用户是 访客，账号关联将失败。了解如何识别和处理 访客用户。

使用账号登录帮助程序 intent 启动身份验证流程。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph>

Dialogflow (Node.js)

const app = dialogflow({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
})

// Intent that starts the account linking flow.
app.intent('Start Signin', conv => {
  conv.ask(new SignIn('To get your account details'))
})

Dialogflow (Java)

private String clientId = "<your_client_id>";

@ForIntent("Start Signin")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

Actions SDK (Node.js)

const app = actionssdk({
  clientId: CLIENT_ID,
})

app.intent('Start Signin', conv => {
  conv.ask(new SignIn('To get your account details'))
})

Actions SDK (Java)

private String clientId = "<your_client_id>";

@ForIntent("actions.intent.TEXT")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

处理数据访问请求

如果 Google 助理请求包含访问令牌， 首先检查访问令牌是否有效且未过期，然后从 用户账号数据库 与令牌关联的用户账号。