OAuth 概念指南 (Dialogflow)

OAuth 帳戶連結類型支援兩種業界標準 OAuth 2.0 流程:隱含授權碼流程。在隱含程式碼流程中,Google 會在使用者的瀏覽器中開啟授權端點。成功登入後,您可以將長期存取權杖回傳給 Google。接著,從 Google 助理傳送至動作的每項要求,都會加入這個存取權杖。

如果符合下列任一情況,建議使用 OAuth 帳戶連結解決方案:

  • 您目前已導入 OAuth 2.0 伺服器,因此無法擴充權杖交換端點,以便支援 Google 通訊協定,以便透過 ID 權杖自動連結及建立帳戶 (也就是在要求中將 intent=getintent=create 參數加到此端點)。

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

重要詞彙

在瞭解 OAuth 的運作方式之前,請先熟悉下列術語:

  • 帳戶登入輔助意圖:您呼叫的輔助意圖,會從 Google 助理要求帳戶連結流程。詳情請參閱帳戶登入一文。
    • 內容字串:您新增至帳戶登入輔助程式意圖的自訂字串,會將字串告知使用者您需要連結帳戶的原因。
  • 授權碼流程:在這個 OAuth 2.0 流程中,Google 會在使用者的瀏覽器中開啟您的授權端點。如果登入成功,您的服務會建立授權碼,並傳回給 Google。Google 會將這組授權碼傳送至您的權杖交換端點,用於驗證代碼的真實性並傳回存取權杖和更新權杖。

    此流程需要兩個端點:

    • 授權端點:負責尋找或向使用者取得資料存取權的同意聲明的端點。此端點會執行以下操作:
      1. 向尚未登入的使用者顯示登入 UI。
      2. 以短期授權碼的形式記錄對於要求存取權的同意。
    • 權杖交換端點:這個端點會取得稱為「權杖」的加密字串,授權動作使用者存取您的服務。這個端點負責以下兩種交易平台:
      1. 將授權碼交換用於長期更新權杖和短期存取權杖。當使用者完成帳戶連結流程時,就會進行此交換。
      2. 將長期更新權杖交換為短期存取權杖。當 Google 因為舊存取權杖過期而需要新的存取權杖時,就會進行這種交換。
  • 隱含程式碼流程:在這個 OAuth 2.0 流程中,Google 會在使用者的瀏覽器中開啟您的授權端點。登入成功後,我們會將長期存取權杖回傳給 Google。接著,從 Google 助理傳送至動作的每項要求,都會加入這個存取權杖。這個流程只需要授權端點。

  • 存取權杖:這個權杖會授權服務存取使用者資料的部分。存取權杖與個別使用者相關聯,因此必須無法解讀。

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

運作方式

本節說明 OAuth 授權碼和隱含流程的一般流程。下一節「OAuth 流程」將說明使用 OAuth 可能產生的各種流程。

授權碼流程大致如下:

  1. 您的動作會詢問使用者是否要將自己的帳戶與您的服務建立連結。
  2. 使用者同意連結帳戶之後,Google 會在使用者的瀏覽器中開啟您的授權端點。如果動作在純語音裝置上啟動,Google 會將該動作傳送到手機。
  3. 使用者登入 (如果尚未登入),並授權 Google 透過您的 API 存取其資料 (如果使用者尚未授予權限)。
  4. 您的服務會建立授權碼,並透過將使用者的瀏覽器重新導向回 Google,並提供要求中附加的授權碼,藉此將授權碼傳回 Google。
  5. Google 會將授權碼傳送至您的權杖交換端點,此端點可驗證程式碼的真實性,並傳回存取權杖更新權杖。存取權杖是短期權杖,您的服務可以接受做為存取 API 的憑證。更新權杖是一種長效權杖,Google 可儲存及在權杖過期時,用來取得新的存取權杖。
  6. 使用者完成帳戶連結流程後,所有從 Google 助理傳送至執行要求 Webhook 的後續要求都會包含存取權杖。

隱含程式碼流程的摘要如下:

  1. 您的動作會詢問使用者是否要將自己的帳戶與您的服務建立連結。
  2. 使用者同意連結帳戶之後,Google 會在使用者的瀏覽器中開啟您的授權端點。
  3. 使用者登入 (如果尚未登入),並授權 Google 透過您的 API 存取其資料 (如果使用者尚未授予權限)。
  4. 您的服務會建立存取權杖,並透過將使用者的瀏覽器重新導向回 Google,藉此將存取權杖傳回至 Google。
  5. 使用者完成帳戶連結流程後,Google 會呼叫服務的 API,並在每項要求中附上存取權杖。您的服務會確認存取權杖授予 Google 存取 API 的權限,然後完成 API 呼叫。

基本授權碼流程如下:

  1. 您的動作會詢問使用者是否要將自己的帳戶與您的服務建立連結。
  2. 使用者同意連結帳戶之後,Google 會在使用者的瀏覽器中開啟您的授權端點。如果動作在純語音裝置上啟動,Google 會將該動作傳送到手機。
  3. 使用者登入 (如果尚未登入),並授權 Google 透過您的 API 存取其資料 (如果使用者尚未授予權限)。
  4. 您的服務會建立授權碼,並透過要求中附加的短期授權碼將使用者的瀏覽器重新導向至 Google,藉此將授權碼傳回 Google。
  5. Google 會將授權碼傳送至您的權杖交換端點,此端點可驗證程式碼的真實性,並傳回存取權杖更新權杖。存取權杖是短期權杖,您的服務可以接受做為存取 API 的憑證。更新權杖是一種長效權杖,Google 可儲存及在權杖過期時,用來取得新的存取權杖。
  6. 使用者完成帳戶連結流程後,所有從 Google 助理傳送至執行要求 Webhook 的後續要求都會包含存取權杖。

OAuth 流程

本節說明 OAuth 適用的各種流程。

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

在上述流程中,您會呼叫 actions.intent.SIGN_IN 輔助意圖來啟動帳戶連結流程。Google 助理會詢問使用者是否要將其帳戶連結至您的服務,並在畫面顯示要求的權限。如果使用者同意,Google 隨即會將使用者在瀏覽器中 重新導向至服務的授權端點。使用者登入 (或根據您的設定建立新帳戶),並授予動作存取其資料的權限。

在這個時間點之後的流程,取決於您是否實作隱含流程或授權碼流程。我們會在以下各節中說明這些流程。

流程 1:使用者透過隱式流程登入

使用者登入及憑證通過驗證後,您的服務會建立長效存取權杖,並將其傳回 Google。此時,動作中的使用者身分會連結至他們登入的帳戶,而 Google 對服務 API 發出的每個 API 呼叫,都會附加存取權杖。

流程 2:使用者透過授權碼流程登入

使用者登入且憑證通過驗證後,您的服務會建立授權碼並傳回 Google。

這組授權碼會傳送到您的權杖交換端點,然後同時傳回存取權杖和更新權杖。此時,動作中的使用者身分會連結至他們用來登入的任何帳戶,且後續從 Google 助理傳送至執行要求的所有要求都包含存取權杖。