透過 OAuth 式 Google 登入簡化帳戶連結程序

以 OAuth 為基礎的 Google 登入「簡化」連結類型，會在以 OAuth 為基礎的帳戶連結上新增 Google 登入功能。這項功能可讓 Google 使用者透過語音順暢地連結帳戶，也能讓使用非 Google 身分註冊服務的使用者連結帳戶。

這類連結會先進行 Google 登入，讓您檢查系統中是否有使用者的 Google 個人資料資訊。如果系統找不到使用者的資訊，就會啟動標準 OAuth 流程。使用者也可以選擇使用 Google 個人資料資訊建立新帳戶。

如要使用簡化連結類型執行帳戶連結，請按照下列一般步驟操作：

1. 首先，請使用者同意存取他們的 Google 個人資料。
2. 使用個人資料中的資訊識別使用者。
3. 如果驗證系統中沒有相符的 Google 使用者，系統會根據您在 Actions 管理中心設定的 Actions 專案，決定是否允許透過語音或僅透過網站建立使用者帳戶，然後繼續執行流程。
   • 如果允許透過語音建立帳戶，請驗證從 Google 收到的 ID 權杖。然後根據 ID 權杖中包含的設定檔資訊建立使用者。
   • 如果不允許透過語音建立帳戶，系統會將使用者轉移至瀏覽器，載入授權頁面並完成使用者建立流程。

支援透過語音建立帳戶

如果允許使用者透過語音建立帳戶，Google 助理會詢問使用者是否要執行下列操作：

• 使用對方的 Google 帳戶資訊在系統上建立新帳戶，或
• 如果使用者有現有的非 Google 帳戶，請使用其他帳戶登入驗證系統。

如要盡量減少帳戶建立流程的阻力，建議允許透過語音建立帳戶。如果使用者想使用現有的非 Google 帳戶登入，才需要離開語音流程。

禁止透過語音建立帳戶

如果禁止透過語音建立使用者帳戶，Google 助理會開啟您提供的使用者驗證網站網址。如果互動發生在沒有螢幕的裝置上，Google 助理會引導使用者前往手機，繼續完成帳戶連結流程。

在下列情況下，建議禁止建立：

• 您不希望允許非 Google 帳戶使用者建立新帳戶，而是希望他們連結至驗證系統中的現有帳戶。舉例來說，如果您提供會員方案，可能需要確保使用者不會失去現有帳戶累積的點數。

• 您必須完全掌控帳戶建立流程。舉例來說，如果您需要在帳戶建立期間向使用者顯示服務條款，可以禁止建立帳戶。

實作以 OAuth 為基礎的 Google 登入「簡化」連結

帳戶會透過業界標準的 OAuth 2.0 流程連結。 Actions on Google 支援隱含和授權碼流程。

在隱式程式碼流程中，Google 會在使用者的瀏覽器中開啟您的授權端點。成功登入後，系統會將長期存取權杖傳回 Google。從現在起，每次透過 Google 助理傳送給您動作的要求中，都會包含這個存取權杖。

在授權碼流程中，您需要兩個端點：

• 授權端點，該端點負責將登入 UI 提供給未登入的使用者，並以簡碼授權代碼的形式，記錄使用者要求的存取權。
• 權杖交換端點，負責以下兩種交換類型：
  1. 交換長期更新權杖的授權碼和短期存取權杖。這項交換作業會在使用者完成帳戶連結流程時進行。
  2. 對短期存取權杖交換交換憑證。當 Google 需要新的存取權杖，因為更新權杖已過期時，就會發生此交換行為。

雖然隱含程式碼流程的實作方式較簡單，但 Google 建議使用隱含流程發布的存取權杖不會過期，因為若權杖與隱含流程搭配使用，就會強制使用者重新連結帳戶。如果基於安全考量而需要權杖過期，您應該考慮改用授權碼流程。

設定專案

如要設定專案以使用簡化連結，請按照下列步驟操作：

1. 開啟 Actions 管理中心，然後選取要使用的專案。
2. 按一下「開發」分頁，然後選擇「帳戶連結」。
3. 將「帳戶連結」旁的切換鈕設為開啟。
4. 在「帳戶建立」部分中，選取「是」。

5. 在「連結類型」中，選取「OAuth 和 Google 登入」和「隱含」。

   

6. 在「Client Information」(客戶資訊) 中，執行下列操作：

   • 為「Google 簽發給動作的用戶端 ID」指派值，以識別來自 Google 的要求。
   • 插入授權和權杖交換端點的網址。

7. 按一下 [儲存]。

導入 OAuth 伺服器

为了支持 OAuth 2.0 隐式流程，您的服务会进行授权 端点。此端点负责 就数据访问征得用户同意。授权端点 向尚未登录的用户显示登录界面，并记录 同意所请求的访问。

当您的 Action 需要调用您的某项授权的 API 时，Google 会使用 此端点来获得用户许可，以在其上调用这些 API 。

由 Google 发起的典型 OAuth 2.0 隐式流会话具有以下特征： 以下流程：

1. Google 会在用户的浏览器中打开您的授权端点。通过 如果用户尚未登录，则可以登录，并且授予 Google 访问 通过您的 API 访问其数据（如果尚未授予权限）。
2. 您的服务会创建一个访问令牌并将其返回给 通过使用访问令牌将用户的浏览器重定向回 Google， 附件。
3. Google 调用您的服务的 API，并使用 。您的服务会验证访问令牌是否向 Google 授予 访问 API 的授权，然后完成 API 调用。

处理授权请求

当您的 Action 需要通过 OAuth 2.0 隐式流程执行账号关联时， Google 会通过包含以下内容的请求将用户发送到您的授权端点： 以下参数：

例如，如果您的授权端点可通过 https://myservice.example.com/auth 访问， 请求可能如下所示：

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

为了让授权端点能够处理登录请求，请执行以下步骤：

1. 验证 client_id 和 redirect_uri 值， 防止向意外或配置错误的客户端应用授予访问权限：

   • 确认 client_id 是否与您的客户端 ID 匹配 分配给 Google。
   • 确认 redirect_uri 指定的网址 参数的格式如下：

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

     YOUR_PROJECT_ID 是项目设置页面上的 ID Actions 控制台界面。

2. 检查用户是否已登录您的服务。如果用户未登录 中，完成服务的登录或注册流程。

3. 生成 Google 将用于访问您的 API 的访问令牌。通过 访问令牌可以是任何字符串值，但必须唯一地表示 令牌对应的用户和客户端，且不得被猜到。

4. 发送 HTTP 响应，将用户浏览器重定向到相应网址 由 redirect_uri 参数指定。添加所有 以下参数：

   • access_token：您刚刚生成的访问令牌
   • token_type：字符串 bearer
   • state：原始状态的未修改状态值 请求 以下是生成的网址示例：

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

Google 的 OAuth 2.0 重定向处理程序将收到访问令牌并确认 state 值没有更改。在 Google 获得 访问令牌，则 Google 会将该令牌附加到后续调用 作为 AppRequest 的一部分添加到您的 Action。

处理自动关联

在用户同意你的 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

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

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

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys (available in JWK or PEM format) to verify the token's signature.

When decoded, the JWT assertion looks like the following example:

{
  "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": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com and that the audience (aud field) is the client ID assigned to your Action.

检查您的身份验证系统中是否已存在该 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",
}

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:

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys (available in JWK or PEM format) to verify the token's signature.

When decoded, the JWT assertion looks like the following example:

{
  "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": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com and that the audience (aud field) is the client ID assigned to your Action.

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":"foo@bar.com"
}

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
}

設計驗證流程的語音使用者介面

檢查使用者是否已通過驗證，然後開始帳戶連結流程

1. 在 Actions Console 中開啟 Actions Builder 專案。
2. 在動作中建立新場景，開始連結帳戶：
   1. 按一下「場景」。
   2. 按一下「新增」 (+) 圖示，即可新增場景。
3. 在新建立的場景中，按一下「條件」的「新增」圖示 add。
4. 新增條件，檢查與對話相關聯的使用者是否為已驗證使用者。如果檢查失敗，動作就無法在對話期間執行帳戶連結，且應改為提供不需要帳戶連結的功能存取權。
   1. 在「條件」下方的 Enter new expression 欄位中，輸入下列邏輯： user.verificationStatus != "VERIFIED"
   2. 在「轉場效果」下方，選取不需要連結帳戶的場景，或是僅限訪客使用的功能進入點場景。

1. 按一下「條件」的「新增」add圖示。
2. 新增條件，在使用者沒有相關聯的身分時觸發帳戶連結流程。
   1. 在「條件」下方的 Enter new expression 欄位中，輸入下列邏輯： user.verificationStatus == "VERIFIED"
   2. 在「Transition」下方，選取「Account Linking」系統場景。
   3. 按一下 [儲存]。

儲存後，專案中會新增名為「<SceneName>_AccountLinking」的帳戶連結系統場景。

自訂帳戶連結場景

1. 在「場景」下方，選取帳戶連結系統場景。
2. 按一下「傳送提示」，並新增簡短句子，向使用者說明動作為何需要存取身分識別資訊 (例如「儲存偏好設定」)。
3. 按一下 [儲存]。

1. 按一下「條件」下方的「如果使用者成功完成帳戶連結」。
2. 設定使用者同意連結帳戶時，流程應如何繼續進行。 舉例來說，呼叫 Webhook 來處理任何必要的自訂商業邏輯，然後返回原始場景。
3. 按一下 [儲存]。

1. 在「條件」下方，按一下「如果使用者取消或關閉帳戶連結」。
2. 設定使用者不同意連結帳戶時，流程應如何進行。舉例來說，傳送確認訊息，然後重新導向至不需要帳戶連結的功能場景。
3. 按一下 [儲存]。

1. 在「條件」下方，按一下「如果發生系統或網路錯誤」。
2. 設定帳戶連結流程因系統或網路錯誤而無法完成時，流程應如何繼續。舉例來說，傳送確認訊息，然後重新導向至不需要帳戶連結的功能場景。
3. 按一下 [儲存]。

處理資料存取要求

如果Google 助理要求包含存取權杖，請先檢查存取權杖是否有效且未過期，然後從使用者帳戶資料庫中擷取與權杖相關聯的使用者帳戶。