透過 OAuth 連結帳戶

OAuth 連結類型支援兩種符合業界標準的 OAuth 2.0 流程，分別是隱含和授權程式碼流程。

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

實作 OAuth 帳戶連結

設定專案

如要將專案設為使用 OAuth 連結，請按照下列步驟操作：

1. 開啟「Actions Console」，然後選取要使用的專案。
2. 按一下「開發」分頁標籤，然後選擇「帳戶連結」。
3. 啟用「帳戶連結」旁的切換鈕。
4. 在「建立帳戶」部分中，選取「否，我只想允許在我的網站上建立帳戶」。

5. 在「連結類型」中，選取「OAuth」和「授權碼」。

   

6. 在「客戶資訊」部分中：

   • 將值指派給「Actions to Google」的用戶端 ID，即可識別來自 Google 的要求。
   • 記下「Google 核發給您動作的用戶端 ID」值；
   • 插入授權和權杖交換端點的網址。

6. 點按「儲存」。

實作 OAuth 伺服器

授權碼流程的 OAuth 2.0 伺服器實作包括 服務透過 HTTPS 提供第一個端點 是授權端點，負責尋找或取得 徵得使用者同意並授予資料存取權授權端點會顯示登入活動 讓尚未登入的使用者顯示使用者介面，並記錄 要求存取權。第二個端點是權杖交換端點 用於取得加密字串 (稱為「權杖」)，授權動作使用者 存取您的服務。

當您的動作需要呼叫服務的其中一個 API 時，Google 會使用這些 多個端點，藉此向使用者取得權限，讓他們能在自己的

Google 啟動的 OAuth 2.0 授權碼流程工作階段如下：

1. Google 會在使用者的瀏覽器中開啟授權端點。如果流程 透過純語音裝置啟動一項動作，則 Google 會將 到手機上

2. 使用者登入 (如果尚未登入) 並將權限授予 Google 如果他們尚未授予權限，可以透過您的 API 存取資料。

3. 您的服務會建立授權碼，並由 透過授權碼將使用者的瀏覽器重新導向回 Google 附加在要求中

4. Google 將授權碼傳送至權杖交換端點 驗證程式碼的真實性，並傳回存取權杖和 更新權杖。存取權杖是服務 以憑證存取 API。更新權杖存在長期 憑證，可供 Google 儲存，用於取得新的存取權杖 過期。

5. 使用者完成帳戶連結流程後， 要求 Google 助理傳送給您的執行要求 Webhook，當中會包含 存取權杖

處理授權要求

你的動作需透過 OAuth 2.0 授權碼進行帳戶連結時 流程時，Google 會透過以下要求將使用者傳送到您的授權端點 包含下列參數：

授權端點參數
client_id	您向 Google 註冊的 Google 用戶端 ID。
redirect_uri	您傳送回應到這項要求的網址。
state	傳回給 Google 的記帳金額，值維持不變 重新導向 URI
scope	選用：一組以空格分隔的範圍字串，指定 也就是 Google 要求授權的資料
response_type	字串 code。

舉例來說，如果您的授權端點位於 https://myservice.example.com/auth， 要求看起來可能像這樣：

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

如要讓授權端點處理登入要求，請按照下列步驟操作：

1. 確認 client_id 與您註冊時使用的 Google 用戶端 ID 相符 Google，且 redirect_uri 與 Google 提供的重新導向網址相符 以及 SLI這些檢查至關重要，是為了避免授予存取權 非預期或設定錯誤的用戶端應用程式。

   如果您支援多個 OAuth 2.0 流程，請一併確認 response_type為 code。

2. 檢查使用者是否已登入您的服務。如果使用者未登入， 完成服務的登入或註冊流程。

3. 產生 Google 用來存取 API 的授權碼。 授權碼可以是任何字串值，但必須不重複 代表使用者、該權杖所屬的用戶端，以及代碼的到期時間 而且您無法憑空猜測您通常會核發授權 驗證碼會在大約 10 分鐘後失效

4. 確認 redirect_uri 參數指定的網址 格式如下：

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

   YOUR_PROJECT_ID 是「專案設定」頁面上的 ID 以及 Actions 主控台

5. 將使用者的瀏覽器重新導向至 redirect_uri 參數。附上 產生的原始值，以及您在重新導向時 方法是附加 code 和 state 參數。以下為 的結果：

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

處理權杖交換要求

服務的權杖交換端點負責兩種權杖 廣告交易平台：

• 交換存取權杖和更新權杖的授權碼
• 交換存取權杖的更新權杖

權杖交換要求包含下列參數：

權杖交換端點參數
client_id	用來識別要求來源為 Google 的字串。此字串必須 在您的系統中註冊為 Google 專屬識別碼。
client_secret	您向 Google 註冊的服務專用密鑰。
grant_type	要交換的權杖類型。兩者皆可 authorization_code 或 refresh_token。
code	如果是 grant_type=authorization_code，程式碼會由 Google 接收的驗證憑證。
redirect_uri	如果 grant_type=authorization_code，這個參數是 用於初始授權要求的網址。
refresh_token	如果為 grant_type=refresh_token，Google 更新憑證權杖會由 Google 從權杖交換端點收到的文字

交換存取權杖和更新權杖的授權碼

使用者登入，且您的授權端點傳回短期授權後 程式碼給 Google，Google 會向您的權杖交換端點傳送要求 存取權杖的授權碼和更新權杖。

在這些要求的 grant_type 值為 authorization_code，其值為 code 是您之前授予 Google 的授權碼值。 以下是以 存取權杖和更新權杖：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

如要交換存取權杖和更新權杖的授權碼，您的 權杖交換端點會回應執行下列步驟的 POST 要求：

1. 驗證 client_id 會將要求來源識別為授權來源。 client_secret 與預期值相符
2. 驗證以下內容：
   • 授權碼有效且未過期，且用戶端 要求中指定的 ID 與 授權碼。
   • redirect_uri 參數指定的網址相同 設為初始授權要求使用的值。
3. 如果您無法驗證上述所有條件，請傳回 HTTP 400 「Bad Request」錯誤，內文為 {"error": "invalid_grant"}。
4. 否則，請使用授權碼中的使用者 ID 產生重新整理 權杖和存取權杖這些符記可以是任何字串值，但必須 可明確代表憑證所屬的使用者和用戶端， 容易猜中如果是存取權杖，請一併記錄權杖的到期時間 (通常是在您核發權杖後一小時)。重新整理權杖沒有期限。
5. 在 HTTPS 回應的內文中傳回下列 JSON 物件：

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }
   

Google 會儲存使用者的存取權杖和更新權杖，並記錄 存取權杖存取權杖到期時，Google 會使用更新項目 取得新的存取權杖。

交換存取權杖的更新權杖

存取權杖到期時，Google 會傳送要求至您的權杖交換端點 來交換更新憑證給新的存取權杖。

在這些要求的 grant_type 值為 refresh_token，其值為 refresh_token 是您先前授予 Google 的更新權杖值。 以下是以 存取權杖：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

如要將更新權杖換成存取權杖，權杖交換端點 回應 POST 要求，執行下列步驟：

1. 驗證 client_id 會將要求來源識別為 且client_secret符合預期 值。
2. 驗證更新權杖是否有效，以及 此請求會與更新權杖關聯的用戶端 ID 相符。
3. 如果您無法驗證上述所有條件，請傳回 HTTP 400 「Bad Request」錯誤，內文為 {"error": "invalid_grant"}。
4. 否則，請使用更新權杖的使用者 ID 產生存取權 產生下一個符記這些符記可以是任何字串值，但必須專門用來 和用戶端，您無法猜測該權杖的用途。 如果是存取權杖，請一併記錄權杖的到期時間 (通常是在您核發權杖後一小時)。
5. 在 HTTPS 內文中傳回下列 JSON 物件 回應：

   {
   "token_type": "熊",
   "access_token": "ACCESS_TOKEN",
   「expires_in」：SECONDS_TO_EXPIRATION
   }

，瞭解如何調查及移除這項存取權。

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

檢查使用者是否已通過驗證，並啟動帳戶連結流程

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

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

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

自訂帳戶連結情境

1. 在「場景」下方，選取帳戶連結系統場景。
2. 按一下「Send 提示」，然後新增簡短句子，說明動作需要存取其身分的原因 (例如「如要儲存偏好設定」)。
3. 點按「儲存」。

1. 在「條件」下方，按一下「如果使用者成功完成帳戶連結」。
2. 設定使用者同意連結帳戶時，流程的後續步驟。 舉例來說，呼叫 Webhook 以處理任何所需的自訂商業邏輯，然後切換回原始場景。
3. 點按「儲存」。

1. 在「條件」下方，按一下「如果使用者取消或關閉帳戶連結」。
2. 如果使用者不同意連結帳戶，請設定流程。例如，傳送已確認的訊息，然後重新導向至提供不需要連結帳戶的功能的場景。
3. 點按「儲存」。

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

處理資料存取要求

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