相互 TLS 認証

Dialogflow が Webhook リクエストに対して開始するネットワーク トラフィックは、パブリック ネットワークで送信されます。両方向のトラフィックの安全性と信頼性を確保するため、Dialogflow は相互 TLS 認証(mTLS)をオプションでサポートします。Dialogflow の標準 TLS handshake 中に、Webhook サーバーは認証局チェーンに従うか、証明書をカスタム CA 証明書と比較して、Dialogflow で検証できる証明書を提示します。Webhook サーバーで mTLS を有効にすると、Dialogflow が検証のために Webhook サーバーに提示したクライアント証明書を認証して、相互信頼の確立を完了します。

デフォルトでは、Dialogflow は SSL.com(CN=Google LLC)によって発行されたクライアント証明書を提示します。

mTLS のリクエスト

mTLS をリクエストするには:

  1. Webhook HTTPS サーバーが TLS handshake 中にクライアント証明書をリクエストするように、準備をします。
  2. 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 をトラストストアに追加するだけで済みます。
  3. クライアント証明書の受信時に検証するように 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 サーバーで、クイックスタートに示されているエージェントを使用します。

  1. 設定例
    1. Dialogflow CX エージェントがシャツの注文を受け取り、スタンドアロン ウェブサーバーを指す Webhook に送信します。
    2. key.pem という名前のファイルの TLS 通信用の秘密鍵。
    3. fullchain.pem という名前のファイルで、公的に信頼できる CA(認証局)によって署名された証明書チェーン。
    4. SSL.com からダウンロードした SSLcomRootCertificationAuthorityRSA.pem という名前のファイル内の SSL.com ルート証明書。
  2. サーバーマシンで openssl s_server プログラムを実行します。
    sudo openssl s_server -key key.pem -cert fullchain.pem -CAfile SSLcomRootCertificationAuthorityRSA.pem -accept 443 -verify 2
  3. リクエストがクライアント マシンからエージェントに送信されます。この例では、リクエストは「L サイズの赤いシャツを購入したい」です。このリクエストは、Dialogflow コンソールを使用するか、API 呼び出しによって送信できます。
  4. サーバーマシンの 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 以上であることを確認してください。