Gegenseitige TLS-Authentifizierung

Der von Dialogflow für Webhook-Anfragen initiierte Netzwerkverkehr wird über ein öffentliches Netzwerk gesendet. Dialogflow unterstützt optional die gegenseitige TLS-Authentifizierung (mTLS), um sicherzustellen, dass der Traffic in beide Richtungen sicher und vertrauenswürdig ist. Während des standardmäßigen TLS-Handshakes von Dialogflow stellt Ihr Webhook-Server ein Zertifikat bereit, das von Dialogflow validiert werden kann. Dazu wird entweder der Zertifizierungsstellenkette gefolgt oder das Zertifikat mit einem benutzerdefinierten Zertifizierungsstellenzertifikat verglichen. Wenn Sie mTLS auf Ihrem Webhook-Server aktivieren, kann dieser das von Dialogflow bereitgestellte Clientzertifikat zur Validierung authentifizieren und so die gegenseitige Vertrauensstellung herstellen.

Standardmäßig stellt Dialogflow ein von SSL.com (CN=Google LLC) ausgestelltes Clientzertifikat bereit.

mTLS anfordern

So fordern Sie mTLS an:

  1. Sie konfigurieren Ihren Webhook-HTTPS-Server so, dass er während des TLS-Handshakes das Clientzertifikat anfordert.
  2. Konfigurieren Sie den mTLS-Trust Store Ihres Webhook-Servers so, dass er dem Root-Zertifikat der SSL.com Root-Zertifizierungsstelle RSA vertraut. Sie können es direkt von SSL.com herunterladen:
    • Stamm-Zertifizierungsstelle: SSL.com Root Certification Authority RSA
    • SHA-256-Fingerprint: 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
    • Prüfungstiefe: Legen Sie die Prüfungstiefe für das TLS-Clientzertifikat auf mindestens 2 fest. Dialogflow sendet das Zwischenzertifikat (SSL.com Client Certificate Intermediate CA RSA R2) während des TLS-Handshakes automatisch. Sie müssen also nur die Stammzertifizierungsstelle zu Ihrem Trust Store hinzufügen.
  3. Konfigurieren Sie Ihren Webhook-Server so, dass das Clientzertifikat bei Erhalt überprüft wird. Wenn Ihr Server oder API-Gateway Clientzertifikate nach Antragsteller oder allgemeinem Namen (Common Name, CN) auf die Zulassungsliste setzt, lassen Sie die folgenden Zertifikatsattribute zu (das Zertifikat enthält keine SAN-Erweiterung (Subject Alternative Name)):

    • Betreff: C=US, ST=California, L=Mountain View, O=Google, OU=Applied Ai, CN=Google LLC
    • Aussteller: C=US, ST=Texas, L=Houston, O=SSL Corp, CN=SSL.com Client Certificate Intermediate CA RSA R2

    Für eine stärkere Validierung sollten Sie sowohl den vollständigen Betreff als auch den Aussteller abgleichen, anstatt nur CN.

Beispielaufruf an einen Webhook-Server mit mTLS

In diesem Beispiel wird der in der Kurzanleitung gezeigte Agent mit einem Webhook-Server verwendet, auf dem openssl ausgeführt wird.

  1. Beispiel für eine Einrichtung
    1. Ein Dialogflow CX-Agent, der Bestellungen für T-Shirts entgegennimmt und an einen Webhook sendet, der auf einen eigenständigen Webserver verweist.
    2. Ein privater Schlüssel für die TLS-Kommunikation in einer Datei mit dem Namen key.pem.
    3. Eine Zertifikatskette, die von einer öffentlich vertrauenswürdigen Zertifizierungsstelle signiert wurde, in einer Datei mit dem Namen fullchain.pem.
    4. Das SSL.com-Root-Zertifikat in einer Datei namens SSLcomRootCertificationAuthorityRSA.pem, die von SSL.com heruntergeladen wurde.
  2. Führen Sie das Programm openssl s_server auf dem Server aus.
    sudo openssl s_server -key key.pem -cert fullchain.pem -CAfile SSLcomRootCertificationAuthorityRSA.pem -accept 443 -verify 2
  3. Eine Anfrage wird von einem Clientcomputer an den Agent gesendet. In diesem Beispiel lautet die Anfrage „Ich möchte ein großes rotes Hemd kaufen“. Diese Anfrage kann über die Dialogflow-Konsole oder über einen API-Aufruf gesendet werden.
  4. Ausgabe von openssl s_server auf dem Servercomputer.
    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
          

Benutzerdefiniertes Clientzertifikat

Benutzerdefinierte Clientzertifikate können auf Agent-Ebene konfiguriert werden, damit sie von allen Webhooks verwendet werden können. Beim Aufruf des Webhooks werden die konfigurierten Zertifikate während des Handshakes präsentiert.

Der private Schlüssel und die Passphrase werden als Secret Manager-Ressource konfiguriert. Der Dialogflow-Dienst-Agent benötigt die Secret Manager-Berechtigungen „Secret Manager Secret Accessor“ für das Secret.

Die Clientzertifikate müssen von einer Zertifizierungsstelle signiert sein, damit der Handshake erfolgreich ist.

Best Practice

Damit Webhook-Anfragen von Ihren eigenen Dialogflow-Agenten initiiert werden, sollten Sie das Dienstidentitätstoken des Inhabers aus dem Autorisierungsheader der Anfrage prüfen. Alternativ können Sie einen Sitzungsparameter überprüfen, der zuvor von einem Authentifizierungsserver auf Ihrer Seite bereitgestellt wurde.

Fehler

Wenn die Validierung des Clientzertifikats fehlschlägt (z. B. weil der Webhook-Server dem Clientzertifikat nicht vertraut), schlägt der TLS-Handshake fehl und die Sitzung wird beendet.

Häufige Fehlermeldungen:

Fehlermeldung Erklärung
Failed to verify client's certificate: x509: certificate signed by unknown authority Dialogflow sendet das Clientzertifikat an den externen Webhook, der es jedoch nicht bestätigen kann. Achten Sie darauf, dass der Trust Store Ihres Webhooks das RSA-Root-Zertifikat der SSL.com Root Certification Authority enthält und dass die Verifizierungstiefe Ihres Servers mindestens 2 beträgt.