Dialogflow が Webhook リクエストに対して開始するネットワーク トラフィックは、パブリック ネットワークで送信されます。両方向のトラフィックの安全性と信頼性を確保するため、Dialogflow は相互 TLS 認証(mTLS)をオプションでサポートします。Dialogflow の標準 TLS handshake 中に、Webhook サーバーは認証局チェーンに従うか、証明書をカスタム CA 証明書と比較して、Dialogflow で検証できる証明書を提示します。Webhook サーバーで mTLS を有効にすると、Dialogflow が検証のために Webhook サーバーに提示したクライアント証明書を認証して、相互信頼の確立を完了します。
デフォルトでは、Dialogflow は SSL.com(CN=Google LLC)によって発行されたクライアント証明書を提示します。
mTLS のリクエスト
mTLS をリクエストするには:
- Webhook HTTPS サーバーが TLS handshake 中にクライアント証明書をリクエストするように、準備をします。
- SSL.com ルート認証局 RSA ルート証明書を信頼するように Webhook サーバーの mTLS トラストストアを構成します。この証明書は、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 handshake 中に中間証明書(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 に送信します。
key.pemという名前のファイルの TLS 通信用の秘密鍵。fullchain.pemという名前のファイルで、公的に信頼できる CA(認証局)によって署名された証明書チェーン。- 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 - リクエストがクライアント マシンからエージェントに送信されます。この例では、リクエストは「L サイズの赤いシャツを購入したい」です。このリクエストは、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 の呼び出し時に、構成された証明書が handshake 中に提示されます。
秘密鍵とパスフレーズは、Secret Manager リソースとして構成されます。Dialogflow サービス エージェントには、シークレットに対する Secret Manager のシークレット アクセサー権限を付与する必要があります。
ハンドシェイクを成功させるには、クライアント証明書が認証局によって署名されている必要があります。
ベスト プラクティス
独自の Dialogflow エージェントから確実に Webhook リクエストが行われるようにするには、リクエストの認証ヘッダーからの署名なしのサービス ID トークンを検証する必要があります。または、以前に認証サーバーによって提供されたセッション パラメータを確認することもできます。
エラー
クライアント証明書の検証が失敗した場合(たとえば、Webhook サーバーがクライアント証明書を信頼していない場合)、TLS handshake が失敗し、セッションが終了します。
一般的なエラー メッセージ:
| エラー メッセージ | 説明 |
|---|---|
| Failed to verify client's certificate: x509: certificate signed by unknown authority(クライアントの証明書を検証できませんでした: x509: 不明な権限で署名された証明書) | Dialogflow はクライアント証明書を外部 Webhook に送信しましたが、外部 Webhook で検証できませんでした。Webhook トラストストアに SSL.com Root Certification Authority RSA ルート証明書が含まれていること、サーバーの検証深度が 2 以上であることを確認してください。 |