Dialogflow가 웹훅 요청을 위해 시작한 네트워크 트래픽은 공개 네트워크를 통해 전송됩니다.
트래픽이 양방향에서 안전하고 신뢰할 수 있도록 하기 위해 Dialogflow는 상호 TLS 인증(mTLS)을 선택적으로 지원합니다.
Dialogflow의 표준 TLS 핸드셰이크 중에 웹훅 서버는 인증 기관 체인에 따라 또는 인증서를 커스텀 CA 인증서와 비교하여 Dialogflow에서 유효성을 검사할 수 있는 인증서를 제공합니다.
웹훅 서버에서 mTLS를 사용 설정하면 검증을 위해 Dialogflow가 웹훅 서버에 제공한 Google 인증서를 인증하여 상호 트러스트 설정을 완료할 수 있습니다.
mTLS 요청
mTLS를 요청하려면 다음 안내를 따르세요.
TLS 핸드셰이크 중에 클라이언트 인증서를 요청하도록 웹훅 HTTPS 서버를 준비합니다.
웹훅 서버는 클라이언트 인증서를 받으면 이를 확인해야 합니다.
클라이언트와 서버가 모두 신뢰할 수 있는 웹훅 서버의 인증서 체인을 설치합니다.
Google 서비스에 연결하는 애플리케이션은 Google Trust Services에 나열된 모든 인증 기관을 신뢰해야 합니다.
루트 인증서를 https://pki.goog/에서 다운로드할 수 있습니다.
mTLS를 사용한 웹훅 서버에 대한 샘플 호출
이 예시에서는 openssl을 실행하는 웹훅 서버와 함께 빠른 시작에 표시된 에이전트를 사용합니다.
샘플 설정
셔츠 주문을 가져와 독립형 웹 서버를 가리키는 웹훅에 전송하는 Dialogflow CX 에이전트
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eDialogflow webhook requests travel over a public network, but Mutual TLS (mTLS) can be enabled to secure and authenticate traffic in both directions.\u003c/p\u003e\n"],["\u003cp\u003eEnabling mTLS on your webhook server allows it to validate the Google certificate presented by Dialogflow, establishing mutual trust between the two systems.\u003c/p\u003e\n"],["\u003cp\u003eTo use mTLS, the webhook server must be configured to request and verify the client certificate during the TLS handshake, and use a trusted certificate chain.\u003c/p\u003e\n"],["\u003cp\u003eDialogflow agents can be configured with custom client certificates that are presented during the mTLS handshake with the webhook, which need to be signed by a Certificate Authority.\u003c/p\u003e\n"],["\u003cp\u003eTo ensure the webhook requests are initiated from your Dialogflow agent, verify the Bearer service identity token, or a session parameter provided by your authentication server.\u003c/p\u003e\n"]]],[],null,["# Mutual TLS authentication\n\nThe network traffic initiated by Dialogflow for webhook requests\nis sent on a public network.\nTo ensure that traffic is both secure and trusted in both directions,\nDialogflow optionally supports\n[Mutual TLS authentication (mTLS)](https://en.wikipedia.org/wiki/Mutual_authentication).\nDuring Dialogflow's standard [TLS handshake](https://hpbn.co/transport-layer-security-tls/#tls-handshake),\nyour webhook server presents a certificate that can be validated by Dialogflow,\neither by following the [Certificate Authority chain](https://hpbn.co/transport-layer-security-tls/#chain-of-trust-and-certificate-authorities)\nor by comparing the certificate to a [Custom CA certificate](/dialogflow/cx/docs/concept/custom-ca).\nBy enabling mTLS on your webhook server, it will be able to authenticate\nthe [Google certificate](https://pki.goog/roots.pem) presented by Dialogflow\nto your webhook server for validation, completing the establishment of mutual\ntrust.\n\nRequesting mTLS\n---------------\n\nTo request mTLS:\n\n1. Prepare your webhook HTTPS server to request the client certificate during the TLS handshake.\n2. Your webhook server should verify the client certificate upon receiving it.\n3. Install a certificate chain for your webhook server, which can be mutually trusted by both client and server. Applications connecting to Google services should trust all the Certificate Authorities listed by [Google Trust Services](https://pki.goog/faq/#faq-27). You can download root certs from: \u003chttps://pki.goog/\u003e.\n\nSample call to a webhook server using mTLS\n------------------------------------------\n\nThis example uses the agent shown in the quickstart with a\n[webhook](/dialogflow/cx/docs/concept/webhook) server\nrunning\n[`openssl`](https://www.openssl.org/docs/manmaster/man1/openssl.html).\n\n1. Sample setup\n 1. A Dialogflow CX agent that takes shirt orders, and sends them to a webhook pointing to a standalone web server.\n 2. A private key for TLS communication in a file named `key.pem`.\n 3. A certificate chain signed by a [publicly-trusted\n CA (Certificate Authority)](/load-balancing/docs/ssl-certificates/self-managed-certs#use_a_publicly-trusted_ca) in a file named `fullchain.pem`.\n2. Execute the [`openssl s_server`](https://www.openssl.org/docs/manmaster/man1/openssl-s_server.html) program in the server machine. \n\n ```console\n sudo openssl s_server -key key.pem -cert fullchain.pem -accept 443 -verify 1\n ```\n3. A request is sent to the agent from a client machine. For this example, the request is \"I want to buy a large red shirt\". This request can be sent using the Dialogflow Console, or through an API call.\n4. Output of `openssl s_server` in the server machine. \n\n ```\n verify depth is 1\n Using default temp DH parameters\n ACCEPT\n depth=2 C = US, O = Google Trust Services LLC, CN = GTS Root R1\n verify return:1\n depth=1 C = US, O = Google Trust Services LLC, CN = GTS CA 1D4\n verify return:1\n depth=0 CN = *.dialogflow.com\n verify return:1\n -----BEGIN SSL SESSION PARAMETERS-----\n MII...\n -----END SSL SESSION PARAMETERS-----\n Client certificate\n -----BEGIN CERTIFICATE-----\n MII...\n -----END CERTIFICATE-----\n subject=CN = *.dialogflow.com\n\n issuer=C = US, O = Google Trust Services LLC, CN = GTS CA 1D4\n\n Shared ciphers:TLS_AES_128_GCM_SHA256:...\n Signature Algorithms: ECDSA+SHA256:...\n Shared Signature Algorithms: ECDSA+SHA256:...\n Peer signing digest: SHA256\n Peer signature type: RSA-PSS\n Supported Elliptic Groups: 0xEAEA:...\n Shared Elliptic groups: X25519:...\n CIPHER is TLS_AES_128_GCM_SHA256\n Secure Renegotiation IS NOT supported\n POST /shirts-agent-webhook HTTP/1.1\n authorization: Bearer ey...\n content-type: application/json\n Host: www.example.com\n Content-Length: 1595\n Connection: keep-alive\n Accept: */*\n User-Agent: Google-Dialogflow\n Accept-Encoding: gzip, deflate, br\n\n {\n \"detectIntentResponseId\": \"a7951ce2-2f00-4af5-a508-4c2cb45698b0\",\n \"intentInfo\": {\n \"lastMatchedIntent\": \"projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665\",\n \"parameters\": {\n \"color\": {\n \"originalValue\": \"red\",\n \"resolvedValue\": \"red\"\n },\n \"size\": {\n \"originalValue\": \"large\",\n \"resolvedValue\": \"large\"\n }\n },\n \"displayName\": \"order.new\",\n \"confidence\": 0.9978873\n },\n \"pageInfo\": {\n \"currentPage\": \"projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/flows/00000000-0000-0000-0000-000000000000/pages/06e6fc4d-c2f2-4830-ab57-7a318f20fd90\",\n \"displayName\": \"Order Confirmation\"\n },\n \"sessionInfo\": {\n \"session\": \"projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/sessions/session-test-001\",\n \"parameters\": {\n \"color\": \"red\",\n \"size\": \"large\"\n }\n },\n \"fulfillmentInfo\": {\n \"tag\": \"confirm\"\n },\n \"messages\": [{\n \"text\": {\n \"text\": [\"Ok, let\\u0027s start a new order.\"],\n \"redactedText\": [\"Ok, let\\u0027s start a new order.\"]\n },\n \"responseType\": \"ENTRY_PROMPT\",\n \"source\": \"VIRTUAL_AGENT\"\n }, {\n \"text\": {\n \"text\": [\"You have selected a large, red shirt.\"],\n \"redactedText\": [\"You have selected a large, red shirt.\"]\n },\n \"responseType\": \"HANDLER_PROMPT\",\n \"source\": \"VIRTUAL_AGENT\"\n }],\n \"text\": \"I want to buy a large red shirt\",\n \"languageCode\": \"en\"\n }ERROR\n shutting down SSL\n CONNECTION CLOSED\n \n ```\n\nCustom Client Certificate\n-------------------------\n\nCustom client certificates can be configured at an agent level to be used by all\nwebhooks. At the time of webhook invocation, the configured certificates will be\npresented during the handshake.\n\nThe private key and passphrase are configured as a Secret Manager\nresource. The Dialogflow service agent will need to be given Secret\nManager Secret Accessor permissions to the secret.\n\nThe client certificates need to be signed by a Certificate Authority for the\nhandshake to be successful.\n\n\nBest Practice\n-------------\n\nTo make sure that webhook requests are initiated from your own Dialogflow agents,\nyou should verify the Bearer\n[service identity token](/dialogflow/cx/docs/concept/webhook#id-token)\nfrom the request's Authorization header. Alternatively, you can verify a session\nparameter provided previously by an authentication server on your side.\n\nErrors\n------\n\nIf the client certificate validation fails\n(for example, the webhook server does not trust the client certificate),\nthe TLS handshake fails and the session terminates.\n\nCommon error messages:"]]
