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

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

如果符合下列任一情況，建議使用 OAuth 和 Google 登入解決方案：

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

如要驗證 OAuth 和 Google 登入解決方案是否適合您，請參閱選擇帳戶連結類型頁面。

重要詞彙

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

• 帳戶登入輔助意圖：您呼叫的輔助意圖，會從 Google 助理要求帳戶連結流程。詳情請參閱帳戶登入一文。
  • 內容字串：您新增至帳戶登入輔助程式意圖的自訂字串，會向使用者說明要連結帳戶的原因。
• 授權碼流程：可以使用 OAuth + Google 登入方式實作的 OAuth 2.0 流程。此流程需要兩個端點：
  • 授權端點：這個端點會向尚未登入的使用者顯示登入 UI。並以短期授權碼的形式記錄同意要求存取的內容。
  • 權杖交換端點：這個端點負責以下兩種交易平台：
    1. 將授權碼交換用於長期更新權杖和短期存取權杖。當使用者完成帳戶連結流程時，就會進行此交換。
    2. 將長期更新權杖交換為短期存取權杖。當 Google 因為舊存取權杖過期而需要新的存取權杖時，就會進行這種交換。
• 隱含程式碼流程：可以使用 OAuth + Google 登入方式實作的 OAuth 2.0 流程。這個流程只需要授權端點。在這個流程中，Google 會在使用者的瀏覽器中開啟您的授權端點。登入成功後，我們會將長期存取權杖回傳給 Google。現在，從 Google 助理傳送至動作的每項要求，都會包含此存取權杖。
• 存取權杖：授權服務存取使用者資料部分內容的憑證。存取權杖與個別使用者相關聯。
• 更新權杖：在短期存取權杖過期後，交換新的存取權杖的憑證。

必要條件

如要使用 OAuth 和 Google 登入連結類型，您需要符合以下條件：

• OAuth 2 伺服器

• 權杖交換端點

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

運作方式

本節將說明 OAuth 和 Google 登入的一般流程。下一節 OAuth 和 GSI 流程會說明基於 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 助理的對話。

OAuth 和 GSI 流程

本節說明 OAuth 和 GSI 可能產生的各種流程。這些圖表說明使用「授權碼」流程 (而非「隱含」程式碼流程) 發生的流程，並假設您使用 Dialogflow 做為動作的自然語言理解解決方案。

注意： 下列流程會假設使用者同意您的動作存取其 Google 個人資料資訊。如果使用者未提供同意聲明，請提供一個有限的流程，讓他們繼續進行動作。詳情請參閱「最佳做法」一節。

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

在上述流程中，您可以使用自訂的內容字串呼叫 actions.intent.SIGN_IN 輔助意圖。此意圖要求使用者授權存取其 Google 個人資料。使用者表示同意後，Google 助理會傳送內含 [e-mail] 設定檔資訊的要求。

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

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

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

注意事項： 下列圖表是以上述「常見步驟」圖表為基礎。

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

注意： Webhook 到使用者的一行代表您建立及自訂的簡易回應。從 Google 助理到 使用者 的線條，代表 Google 助理擁有的提示，且自訂選項有限 (需要權限的要求一律由 Google 助理擁有)。從使用者的角度來看，這兩種回應都是透過 Google 助理傳送。

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

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

由於您是透過語音啟用帳戶建立功能，而且 [e-mail] 的後端中沒有，Google 助理會詢問使用者是否要執行下列任一操作：

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

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

注意： 您也可以允許使用者透過其他供應商建立新帳戶。這些供應商就是您在授權頁面上提供的供應商。

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

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

注意： 新帳戶通常不會設定密碼。建議您將 Google 登入功能新增至其他平台，讓使用者得以在所有應用程式途徑中透過 Google 登入。您也可以透過電子郵件傳送啟動密碼復原流程的連結，讓使用者設定在其他平台上登入的密碼。

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

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

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

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

注意： 您也可以允許使用者透過其他供應商建立新帳戶。這些提供者就是您在授權頁面上提供的供應商。

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

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

停用建立語音帳戶的流程

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

注意事項： 下列圖表是以上述「常見步驟」圖表為基礎。

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

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

驗證使用者憑證後，您的服務會將存取權杖和更新權杖傳回 Google。動作中的使用者身分現已連結至非 Google 帳戶。使用者的原始要求 (「Order my 成本效益」) 和自訂意圖 order_drink. 相符。接著，Webhook 會處理相符意圖的執行要求，並向資料庫查詢 [e-mail] 的一般順序，因為使用者是新的使用者。接著，動作即可要求使用者設定一般的訂單。