權杖代理是 Omnichannel Gateway 的核心架構元件，可為面向大眾的即時通訊介面 (特別是 WebChat) 提供安全且受管理的驗證
本文說明權杖代理程式的用途、為什麼必須使用權杖代理程式 (而非不進行驗證)，以及使用 Omnichannel Gateway 時，權杖代理程式如何管理安全工作階段。
什麼是權杖代理人？
將即時通訊小工具 (例如 WebChat) 部署到對外網站時，瀏覽器中的使用者需要與後端服務專員互動。直接在用戶端公開虛擬代理程式會帶來許多風險：
- 無法控管工作階段符記生命週期
- 無法控管誰能取得工作階段和權杖，例如僅限網站的登入使用者
- 沒有可供調整參數的中介機構
權杖代理可做為安全的中介資源，您可設定該資源，允許支援此流程的機制。公開 WebChat SDK 不會允許所有代理人以未經驗證的方式進行對話，而是會與權杖代理人通訊，取得短期、工作階段鎖定的存取權杖，然後用來與代理人對話。
設定權杖代理程式
如要設定最簡單的權杖代理程式，請定義權杖代理程式資源，並指定顯示名稱和簽發者服務帳戶。例如：
{
"displayName": "A broker",
"issuerServiceAccount": "YOUR_BROKER_SERVICE_ACCOUNT_HERE"
}
issuerServiceAccount 是您授予 IAM 權限的服務帳戶 (例如 roles/agenticapplications.user)。啟動網頁即時通訊連線時，我們會檢查這項權限，確認權杖代理程式有權建立工作階段並與代理程式通訊。
如要進一步瞭解如何在網頁即時通訊環境中使用代理程式，請參閱「使用預建 SDK 設定 WebChat」。如要設定 reCAPTCHA 驗證等進階功能，請參閱自訂權杖代理程式。
使用中介服務而非允許未經驗證流量的原因
理論上，您可以允許匿名存取代理程式，但這麼做會造成重大安全和營運風險：
- 防濫用和配額：如果沒有驗證，網際網路上的任何人都能濫發訊息給虛擬代理，耗盡 API 配額並產生高額費用。
- 工作階段隔離：中介服務可確保每位訪客都有自己的加密隔離聊天工作階段，防止使用者竊聽或劫持其他使用者的對話。
- 存取權控管政策：系統可透過已驗證的權杖，在 API 閘道層級驗證要求，讓您立即撤銷工作階段或封鎖可疑活動。
因此，Omnichannel Gateway 不允許匿名存取服務專員，且強制執行至少最基本的安全功能，例如工作階段鎖定。
WebChat 工作階段的生命週期
資訊：本節內容適用於我們提供的預建 WebChat，但任何自訂實作方式都非常相似。
使用者造訪託管 WebChat 小工具的網頁時，預先建構的 SDK 會與權杖代理程式協調安全交握，以取得憑證並維護即時通訊串流。
下圖說明這個端對端生命週期，包括初始權杖授予、工作階段繫結和定期權杖重新整理：
驗證和對話流程大致包含下列階段：
- WebChat SDK 會向權杖代理人要求新的工作階段，權杖代理人會驗證要求，並傳回專屬工作階段 ID，以及存取和重新整理權杖 (效期短)。存取權杖會繫結至已設定的
issuerServiceAccount。 - SDK 會使用存取權杖連線至 Omnichannel Gateway；閘道會驗證權杖的有效性和工作階段完整性，如果權杖過期或工作階段 ID 無效，就會拒絕存取。
- 連線要求獲得核准後，系統會開啟全雙工通訊串流，讓使用者和閘道順暢地交換訊息，不必在個別訊息中附加權杖。
- 在存取權杖過期前，SDK 會主動使用更新權杖，從權杖代理程式取得新的工作階段鎖定存取權杖。如果更新權杖過期或遭撤銷，系統會自動清除工作階段並重新啟動流程。
進一步瞭解權杖的生命週期
為確保安全性，核發的授權憑證採用雙權杖系統：
- 首次核發：使用者啟動新的即時通訊工作階段時，WebChat SDK 會使用
REFRESH_TOKEN授權類型呼叫權杖中介服務的issueToken端點。權杖代理程式會產生專屬工作階段 ID 和安全且長期有效的更新權杖。這個更新權杖的安全雜湊會儲存在後端資料庫中，而權杖本身則會連同初始的短期存取權杖一併傳回給用戶端。 - 短期存取權杖：存取權杖是結構化的 JSON Web Token (JWT)，預設會在 15 分鐘後失效。設定權杖代理程式 (
tokenExpiry) 時，您可以將這項設定設為最多一小時。用戶端 SDK 會自動檢查權杖到期時間，並視需要以無訊息方式重新整理。 - 定期背景重新整理：目前的存取權杖即將過期時 (約一分鐘前)，用戶端 SDK 會使用
ACCESS_TOKEN授權類型和安全refreshToken，呼叫代理程式的issueToken端點。代理程式會驗證更新權杖，並傳回新的存取權杖，不會中斷使用者的有效即時通訊工作階段。 - 更新權杖到期和管理：為確保最高安全性，長期有效的更新權杖有自己的到期時間。雖然您可以在 Token Broker 資源上直接設定存取權杖的生命週期，但 Omnichannel Gateway 會管理長期更新權杖的生命週期：在更新要求期間，閘道會根據儲存的雜湊值驗證權杖，並檢查權杖的到期時間戳記。如果更新權杖已過期，閘道會拒絕要求，並提示用戶端 SDK 清除工作階段，然後重新啟動權杖握手程序。
- 撤銷更新權杖：您可以使用權杖仲介服務的
revokeRefreshTokenAPI 端點，並提供權杖的專屬 ID，立即讓有效的工作階段失效。撤銷作業對於安全性和工作階段管理至關重要，例如使用者登出網頁應用程式、系統偵測到可疑或濫用聊天行為，或是使用者裝置遭到入侵時，都必須執行這項作業。撤銷後，閘道會封鎖後續的任何背景重新整理嘗試，並立即終止即時通訊工作階段。
開啟即時通訊工作階段時，用戶端應同時提供工作階段 ID 和存取權杖。由於這些聲明會直接嵌入已簽署的 JWT 酬載，Omnichannel Gateway 會驗證並強制執行這項規定，確保使用這個權杖傳送的訊息只會對應至特定鎖定的工作階段 ID。即使惡意行為人攔截了使用者的有效 JWT 存取權杖，也無法用來偽造或存取任何其他使用者的工作階段。
安全設定發卡機構服務帳戶
權杖代理程式會利用指定的核發者服務帳戶簽署及建立 JWT 存取權杖。為維持高安全防護等級，請務必為這個服務帳戶設定最低權限。凡是透過中介服務取得存取權杖的使用者，都會獲得這個服務帳戶的授權，並有權以該使用者身分執行動作。
- 用戶端瀏覽器應用程式只需要傳送及接收代理商即時通訊訊息的權限。因此，
- 建議您只授予服務帳戶用於
issuerServiceAccount的角色，因此只會授予omnichannelEndpointConfigs.interact。
後續步驟
- 如要導入更進階的工作階段和驗證架構，請參閱自訂權杖代理程式指南。