OAuth 式 Google 登入 (簡化) 連結概念指南

如果採用 OAuth 為基礎的 Google 登入「簡易」連結類型,除了 OAuth 帳戶連結之外,系統也會新增 Google 登入功能。如果您在動作中使用這種連結類型,流程會以 Google 登入開始,方便您檢查系統中是否有使用者的 Google 個人資訊。否則,系統會先執行標準的 OAuth 流程。提供這兩種連結類型後,使用者就能在您的動作中將自己的身分連結至 Google 或非 Google 帳戶。他們也可以選擇使用自己的 Google 個人資料建立新帳戶。

如果符合下列任一情況,則建議使用簡化連結解決方案:

  • 您的動作橫跨多個平台 (例如,如果您的動作適用於 Android 應用程式)。
  • 您目前擁有驗證系統,而且想讓使用者將自己的身分與非 Google 帳戶建立連結。例如,如果你提供會員方案,且想確保使用者不會失去現有帳戶中累積的點數,

如要驗證精簡連結是否為適合您的解決方案,請參閱選擇您的帳戶連結類型頁面。

重要詞彙

閱讀簡化連結的運作方式之前,請先熟悉下列詞彙:

  • Google ID 權杖:指已簽署的使用者身分,其中包含使用者的基本 Google 個人資料 (使用者名稱、電子郵件地址和個人資料相片)。Google ID 權杖是一種 JSON Web Token (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"
}
  • user.verificationStatus系統設定的屬性,指出目前的工作階段是否有已驗證的使用者。

  • user.accountLinkingStatus系統設定的屬性,表示目前工作階段中的使用者是否有已連結的身分。

  • 帳戶連結系統情境:這個預先定義的情境會導入帳戶連結確認流程,可配合特定用途進行自訂。

  • 授權碼流程:您可以使用簡化連結實作的 OAuth 2.0 流程。此流程需要兩個端點:

    • 授權端點:這個端點會向尚未登入的使用者顯示登入 UI。並以短期授權碼的形式記錄同意要求存取的內容。
    • 權杖交換端點:這個端點負責以下兩種交易平台:
      1. 將授權碼交換用於長期更新權杖和短期存取權杖。當使用者完成帳戶連結流程時,就會進行此交換。
      2. 將長期更新權杖交換為短期存取權杖。當 Google 因為舊存取權杖過期而需要新的存取權杖時,就會進行這種交換。
  • 隱含程式碼流程:可透過簡化連結實作的 OAuth 2.0 流程。這個流程只需要授權端點。在這個流程中,Google 會在使用者的瀏覽器中開啟您的授權端點。登入成功後,我們會將長期存取權杖回傳給 Google。現在,從 Google 助理傳送至動作的每項要求,都會包含此存取權杖。

  • 存取權杖:授權服務存取使用者資料部分內容的憑證。存取權杖與個別使用者相關聯。

  • 更新權杖:在短期存取權杖過期後,交換新的存取權杖的憑證。

必要條件

如要使用簡化連結類型,您需要符合以下條件:

  • OAuth 2.0 伺服器
  • 權杖交換端點

    憑證交換端點需要延伸,以新增 Google 通訊協定的支援功能,以便透過 ID 權杖自動連結及建立帳戶 (亦即在要求中為此端點加入 intent=getintent=create 參數)。

運作方式

本節將說明簡化連結的一般流程。下一節「簡化連結流程」說明瞭 a) 透過語音啟用或停用帳戶建立流程時可能發生的各種流程,以及 b) 使用隱式或授權碼流程。

基本流程如下:

  1. 您的動作要求使用者同意存取其 Google 個人資料。
  2. 使用者表示同意後,您的動作會收到 Google ID 權杖,其中包含使用者的 Google 設定檔資訊。
  3. 你必須驗證權杖並解碼,才能讀取設定檔內容。
  4. 您的動作會使用此符記檢查使用者的 Google 設定檔資訊是否存在於您的系統中。
    1. 如果是,則使用者已使用 Google 帳戶登入您的系統,而 Google 助理會將使用者身分連結至其 Google 帳戶。使用者可以透過已連結帳戶繼續與 Google 助理對話。
    2. 如果沒有,請參閱步驟 5。
  5. 使用者可以建立) 使用自己的 Google 個人資料建立新帳戶,或是 b) 使用其他帳戶登入系統。系統會根據您是否透過語音啟用或停用帳戶建立功能,向使用者顯示的選項會有所不同。如果使用者選擇透過其他帳戶登入系統,則標準 OAuth 流程會開始。
  6. 使用者建立新帳戶或透過其他供應商登入後,您的服務會將存取權杖傳回 Google。(如果您使用授權碼流程,您的服務也會傳回更新權杖)。
  7. 使用者現在可以透過已連結帳戶繼續進行與 Google 助理的對話。

簡化連結流程

本節將說明簡化連結後可能發生的各種流程。這些圖表說明「授權碼」流程 (而非「隱含」程式碼流程) 發生的流程,並假設您使用的是 Actions Builder。

每個流程都包含以下常見步驟:使用者叫用動作後:

在上述流程中,您將轉換至帳戶連結系統場景,並提供自訂的理由。場景要求使用者授予其 Google 個人資料存取權限。使用者表示同意後,Google 助理會傳送內含 user@gmail.com 設定檔資訊的要求。

在這個時間點之後的流程,取決於您是否設定使用語音進行帳戶連結,以及使用者資訊是否已存在於您的系統中。以下各節將說明這些流程。

已啟用語音帳戶的建立流程

本節詳細說明透過語音建立帳戶時可能發生的帳戶連結流程。

流程 1:您的系統中已有使用者資訊

在這種情況下,user@gmail.com 代表的使用者存在於後端,因此權杖交換端點會傳回使用者的權杖。動作中使用者的身分現已連結至他們的 Google 帳戶。使用者的原始要求 (「幫我訂購」) 與使用者意圖 order_drink. 相符。接著,Webhook 會處理相符意圖的執行要求,並查詢資料庫的 user@gmail.com 正常順序。讓使用者可以繼續與 Google 助理對話。

流程 2:使用者資訊不存在,且使用者建立帳戶

由於您是透過語音啟用帳戶建立功能,而且 user@gmail.com 的後端中沒有,Google 助理會詢問使用者是否要執行下列任一操作:

a) 透過語音在系統上建立新帳戶

b) 使用其他帳戶登入系統

在這種情況下,使用者選擇透過語音建立新帳戶。Google 會透過要求建立帳戶的要求,呼叫服務的權杖交換端點。這項要求內含 Google ID 權杖,其中包含建立新帳戶所需的元件。接著,您就可以使用這個權杖的資訊 (使用者的姓名和電子郵件地址) 為使用者建立帳戶。

帳戶建立完成後,您的服務會傳回用於新建帳戶的存取權杖和更新權杖。動作中的使用者身分現已連結至其 Google 帳戶。使用者的原始要求 (「幫我訂購」) 符合使用者意圖 order_drink.。接著,Webhook 會處理相符意圖的執行要求,並向資料庫查詢 user@gmail.com 的一般訂單,因為使用者是新的使用者。接著,動作就能詢問使用者想訂購什麼商品。

流程 3:使用者資訊不存在,而使用者登入其他帳戶

由於你可透過語音建立帳戶,因此 Google 助理會詢問使用者是否要執行下列任一操作:

a) 透過語音在系統上建立新帳戶

b) 使用其他帳戶登入系統

在這種情況下,使用者會選擇以其他帳戶登入,這會啟動標準 OAuth 流程。如果在純語音裝置上開始流程,Google 會將執行作業轉移至手機。然後,Google 會在使用者的瀏覽器中開啟您的授權端點,並且根據您的設定,使用者可以選擇是否使用未使用 Google 登入的現有帳戶登入服務,或者 b) 使用其他供應商建立新帳戶。如要進一步瞭解 OAuth 流程,請參閱 OAuth 連結概念指南

驗證使用者憑證後,您的服務會將存取權杖和更新權杖傳回 Google。動作中的使用者身分現已連結至非 Google 帳戶。使用者的原始要求 (「Order my self」) 符合使用者意圖 order_drink.。接著,Webhook 會處理相符意圖的執行要求,並向資料庫查詢 user@gmail.com 的一般訂單,因為使用者是新的使用者。接著,動作就能詢問使用者想訂購的商品,或請他們設定一般的訂單。

停用建立語音帳戶的流程

本節將詳細說明透過語音停用帳戶建立程序時可能發生的帳戶連結流程。

流程 4:使用者資訊不存在

您並未透過語音啟用帳戶建立功能,且使用者不在您的後端中,因此標準 OAuth 流程會啟動。Google 助理會在使用者的瀏覽器中開啟授權端點 (如果流程是在僅限語音的裝置上開始,Google 會透過螢幕將執行作業轉移至有螢幕的裝置)。如果使用者已使用其他帳戶註冊您的服務,使用者可以選擇 a) 登入該服務,或是 b) 改用其他供應商的新帳戶。如要進一步瞭解 OAuth 流程,請參閱 OAuth 連結概念指南

驗證使用者憑證後,您的服務會將存取權杖和更新權杖傳回 Google。動作中的使用者身分現已連結至非 Google 帳戶。使用者的原始要求 (「Order my self」) 符合使用者意圖 order_drink.。接著,Webhook 會處理相符意圖的執行要求,並向資料庫查詢 user@gmail.com 的一般訂單,因為使用者是新的使用者。接著,動作即可要求使用者設定一般的訂單。