Autentikasi TLS bersama

Traffic jaringan yang dimulai oleh Dialogflow untuk permintaan webhook dikirim di jaringan publik. Untuk memastikan bahwa traffic aman dan tepercaya di kedua arah, Dialogflow secara opsional mendukung Autentikasi TLS bersama (mTLS). Selama TLS handshake standar Dialogflow, server webhook Anda akan menampilkan sertifikat yang dapat divalidasi oleh Dialogflow, baik dengan mengikuti Certificate Authority chain maupun dengan membandingkan sertifikat dengan Sertifikat CA kustom. Dengan mengaktifkan mTLS di server webhook, server tersebut dapat mengautentikasi sertifikat klien yang diberikan oleh Dialogflow ke server webhook Anda untuk validasi, sehingga menyelesaikan pembentukan kepercayaan bersama.

Secara default, Dialogflow menampilkan sertifikat klien yang diterbitkan oleh SSL.com (CN=Google LLC).

Meminta mTLS

Untuk meminta mTLS:

  1. Siapkan server HTTPS webhook Anda untuk meminta sertifikat klien selama TLS handshake.
  2. Konfigurasikan trust store mTLS server webhook Anda untuk memercayai root certificate SSL.com Root Certification Authority RSA, yang dapat Anda download langsung dari SSL.com:
    • Root CA: SSL.com Root Certification Authority RSA
    • Sidik jari 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
    • Verification depth: Tetapkan kedalaman verifikasi sertifikat klien TLS ke setidaknya 2. Dialogflow otomatis mengirimkan intermediate certificate (SSL.com Client Certificate Intermediate CA RSA R2) selama TLS handshake, sehingga Anda hanya perlu menambahkan root CA ke trust store.
  3. Konfigurasikan server webhook Anda untuk memverifikasi sertifikat klien setelah menerimanya. Jika server atau gateway API Anda mengizinkan sertifikat klien berdasarkan subjek atau Nama Umum (CN), izinkan atribut sertifikat berikut (sertifikat tidak menyertakan ekstensi Subject Alternative Name (SAN)):

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

    Untuk validasi yang lebih kuat, cocokkan subjek dan penerbit lengkap, bukan CN saja.

Contoh panggilan ke server webhook menggunakan mTLS

Contoh ini menggunakan agen yang ditampilkan dalam panduan memulai dengan server webhook yang menjalankan openssl.

  1. Contoh penyiapan
    1. Agen Dialogflow CX yang menerima pesanan kaus, dan mengirimkannya ke webhook yang mengarah ke server web mandiri.
    2. Kunci pribadi untuk komunikasi TLS dalam file bernama key.pem.
    3. Rantai sertifikat yang ditandatangani oleh CA (Certificate Authority) yang dipercaya secara publik dalam file bernama fullchain.pem.
    4. Root certificate SSL.com dalam file bernama SSLcomRootCertificationAuthorityRSA.pem, yang didownload dari SSL.com.
  2. Jalankan program openssl s_server di mesin server.
    sudo openssl s_server -key key.pem -cert fullchain.pem -CAfile SSLcomRootCertificationAuthorityRSA.pem -accept 443 -verify 2
  3. Permintaan dikirim ke agen dari mesin klien. Untuk contoh ini, permintaannya adalah "Saya ingin membeli kemeja merah besar". Permintaan ini dapat dikirim menggunakan Konsol Dialogflow, atau melalui panggilan API.
  4. Output openssl s_server di mesin 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
          

Sertifikat Klien Kustom

Sertifikat klien kustom dapat dikonfigurasi di tingkat agen untuk digunakan oleh semua webhook. Pada saat pemanggilan webhook, sertifikat yang dikonfigurasi akan ditampilkan selama handshake.

Kunci pribadi dan frasa sandi dikonfigurasi sebagai resource Secret Manager. Agen layanan Dialogflow harus diberi izin Secret Manager Secret Accessor ke secret.

Sertifikat klien harus ditandatangani oleh Certificate Authority agar handshake berhasil.

Praktik Terbaik

Untuk memastikan bahwa permintaan webhook dimulai dari agen Dialogflow Anda sendiri, Anda harus memverifikasi token identitas layanan Bearer dari header Authorization permintaan. Atau, Anda dapat memverifikasi parameter sesi yang disediakan sebelumnya oleh server autentikasi di pihak Anda.

Error

Jika validasi sertifikat klien gagal (misalnya, server webhook tidak memercayai sertifikat klien), TLS handshake akan gagal dan sesi akan dihentikan.

Pesan error umum:

Pesan error Penjelasan
Failed to verify client's certificate: x509: certificate signed by unknown authority Dialogflow mengirimkan sertifikat kliennya ke webhook eksternal, tetapi webhook eksternal tidak dapat memverifikasinya. Pastikan trust store webhook Anda menyertakan root certificate RSA Root Certification Authority SSL.com dan kedalaman verifikasi server Anda minimal 2.