Dialogflow 針對 Webhook 要求啟動的網路流量,會透過公用網路傳送。為確保雙向流量安全且可信,Dialogflow 支援相互 TLS 驗證 (mTLS)。在 Dialogflow 的標準 TLS 握手期間,Webhook 伺服器會提供可由 Dialogflow 驗證的憑證,驗證方式包括遵循憑證授權單位鏈結,或將憑證與自訂 CA 憑證進行比較。在 Webhook 伺服器上啟用 mTLS 後,伺服器就能驗證 Dialogflow 提供的用戶端憑證,完成雙向信任關係的建立。
根據預設,Dialogflow 會提供 SSL.com (CN=Google LLC) 核發的用戶端憑證。
要求 mTLS
如要要求 mTLS,請按照下列步驟操作:
- 準備 Webhook HTTPS 伺服器,在 TLS 握手期間要求用戶端憑證。
- 設定 Webhook 伺服器的 mTLS 信任存放區,信任 SSL.com Root Certification Authority RSA 根憑證,您可以直接從 SSL.com 下載:
- 根 CA:
SSL.com Root Certification Authority RSA - SHA-256 指紋:
85:66:6A:56:2E:E0:BE:5C:E9:25:C1:D8:89:0A:6F:76:A8:7E:C1:6D:4D:7D:5F:29:EA:74:19:CF:20:12:3B:69 - 驗證深度:將 TLS 用戶端憑證驗證深度設為至少
2。Dialogflow 會在 TLS 握手期間自動傳送中繼憑證 (SSL.com Client Certificate Intermediate CA RSA R2),因此您只需將根 CA 新增至信任存放區。
- 根 CA:
請設定 Webhook 伺服器,在收到用戶端憑證時進行驗證。如果伺服器或 API 閘道依主體或一般名稱 (CN) 將用戶端憑證加入許可清單,請允許下列憑證屬性 (憑證不含主體別名 (SAN) 擴充功能):
- 主旨:
C=US, ST=California, L=Mountain View, O=Google, OU=Applied Ai, CN=Google LLC - 核發者:
C=US, ST=Texas, L=Houston, O=SSL Corp, CN=SSL.com Client Certificate Intermediate CA RSA R2
如要強化驗證,請比對完整主體和核發者,而非僅比對
CN。- 主旨:
使用 mTLS 呼叫 Webhook 伺服器的範例
這個範例使用快速入門導覽課程中顯示的代理,並搭配執行 openssl 的 Webhook 伺服器。
- 設定範例
- Dialogflow CX 代理,可接受襯衫訂單,並將訂單傳送至指向獨立網路伺服器的 Webhook。
- 用於 TLS 通訊的私密金鑰,位於名為
key.pem的檔案中。 - 由公開信任的 CA (憑證授權單位) 簽署的憑證鏈結,位於名為
fullchain.pem的檔案中。 - SSL.com 根憑證,位於名為
SSLcomRootCertificationAuthorityRSA.pem的檔案中,從 SSL.com 下載。
-
在伺服器機器中執行
openssl s_server程式。sudo openssl s_server -key key.pem -cert fullchain.pem -CAfile SSLcomRootCertificationAuthorityRSA.pem -accept 443 -verify 2 - 要求會從用戶端機器傳送至代理程式。在這個範例中,要求是「我想買一件大號紅色襯衫」。這項要求可以透過 Dialogflow 控制台或 API 呼叫傳送。
-
伺服器機器中
openssl s_server的輸出內容。verify depth is 2 Using default temp DH parameters ACCEPT depth=2 C = US, ST = Texas, L = Houston, O = SSL Corporation, CN = SSL.com Root Certification Authority RSA verify return:1 depth=1 C = US, ST = Texas, L = Houston, O = SSL Corp, CN = SSL.com Client Certificate Intermediate CA RSA R2 verify return:1 depth=0 C = US, ST = California, L = Mountain View, O = Google, OU = Applied Ai, CN = Google LLC verify return:1 -----BEGIN SSL SESSION PARAMETERS----- MII... -----END SSL SESSION PARAMETERS----- Client certificate -----BEGIN CERTIFICATE----- MII... -----END CERTIFICATE----- subject=C = US, ST = California, L = Mountain View, O = Google, OU = Applied Ai, CN = Google LLC issuer=C = US, ST = Texas, L = Houston, O = SSL Corp, CN = SSL.com Client Certificate Intermediate CA RSA R2 Shared ciphers:TLS_AES_128_GCM_SHA256:... Signature Algorithms: ECDSA+SHA256:... Shared Signature Algorithms: ECDSA+SHA256:... Peer signing digest: SHA256 Peer signature type: RSA-PSS Supported Elliptic Groups: 0xEAEA:... Shared Elliptic groups: X25519:... CIPHER is TLS_AES_128_GCM_SHA256 Secure Renegotiation IS NOT supported POST /shirts-agent-webhook HTTP/1.1 authorization: Bearer ey... content-type: application/json Host: www.example.com Content-Length: 1595 Connection: keep-alive Accept: */* User-Agent: Google-Dialogflow Accept-Encoding: gzip, deflate, br { "detectIntentResponseId": "a7951ce2-2f00-4af5-a508-4c2cb45698b0", "intentInfo": { "lastMatchedIntent": "projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665", "parameters": { "color": { "originalValue": "red", "resolvedValue": "red" }, "size": { "originalValue": "large", "resolvedValue": "large" } }, "displayName": "order.new", "confidence": 0.9978873 }, "pageInfo": { "currentPage": "projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/flows/00000000-0000-0000-0000-000000000000/pages/06e6fc4d-c2f2-4830-ab57-7a318f20fd90", "displayName": "Order Confirmation" }, "sessionInfo": { "session": "projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/sessions/session-test-001", "parameters": { "color": "red", "size": "large" } }, "fulfillmentInfo": { "tag": "confirm" }, "messages": [{ "text": { "text": ["Ok, let\u0027s start a new order."], "redactedText": ["Ok, let\u0027s start a new order."] }, "responseType": "ENTRY_PROMPT", "source": "VIRTUAL_AGENT" }, { "text": { "text": ["You have selected a large, red shirt."], "redactedText": ["You have selected a large, red shirt."] }, "responseType": "HANDLER_PROMPT", "source": "VIRTUAL_AGENT" }], "text": "I want to buy a large red shirt", "languageCode": "en" }ERROR shutting down SSL CONNECTION CLOSED
自訂用戶端憑證
您可以在代理層級設定自訂用戶端憑證,供所有 Webhook 使用。叫用 Webhook 時,系統會在握手期間提供設定的憑證。
私密金鑰和通關密語會設為 Secret Manager 資源。Dialogflow 服務代理必須具備 Secret Manager Secret 存取者權限,才能存取 Secret。
用戶端憑證必須由憑證授權單位簽署,才能成功進行交握。
最佳做法
為確保 Webhook 要求是由您自己的 Dialogflow 代理啟動,請驗證要求授權標頭中的 Bearer 服務身分權杖。或者,您也可以驗證先前由驗證伺服器提供的階段參數。
錯誤
如果用戶端憑證驗證失敗 (例如 Webhook 伺服器不信任用戶端憑證),TLS 握手就會失敗,工作階段也會終止。
常見錯誤訊息:
| 錯誤訊息 | 說明 |
|---|---|
| 無法驗證用戶端憑證:x509:憑證由不明授權單位簽署 | Dialogflow 會將用戶端憑證傳送至外部 Webhook,但外部 Webhook 無法驗證憑證。請確認 Webhook 信任存放區包含 SSL.com 根憑證授權單位 RSA 根憑證,且伺服器的驗證深度至少為 2。 |