OAuth 連結概念指南

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

如果符合下列情況，建議您使用 OAuth 連結解決方案：

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

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

重要詞彙

在瞭解 OAuth 連結的運作方式之前，請先熟悉以下術語：

  • user.verificationStatus：系統設定的屬性，指出目前的工作階段是否有已驗證的使用者。

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

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

  • 授權碼流程：在這個 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 連結的各種流程。

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

在上述流程中，您將轉換至帳戶連結系統場景，並提供自訂的理由。Google 助理會詢問使用者是否要將帳戶連結至您的服務，並在畫面顯示要求的權限。如果使用者同意，Google 隨即會將使用者在瀏覽器中 重新導向至服務的授權端點。使用者登入 (或根據您的設定建立新帳戶)，並授予動作存取其資料的權限。

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

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

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

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

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

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