El tráfico de red iniciado por Dialogflow para las solicitudes de webhook se envía en una red pública. Para garantizar que el tráfico sea seguro y confiable en ambas direcciones, Dialogflow admite de forma opcional la autenticación TLS mutua (mTLS). Durante el protocolo de enlace TLS estándar de Dialogflow, tu servidor de webhook presenta un certificado que Dialogflow puede validar, ya sea siguiendo la cadena de la autoridad certificadora o comparando el certificado con un certificado de AC personalizado. Si habilitas mTLS en tu servidor de webhook, este puede autenticar el certificado de cliente que Dialogflow presenta a tu servidor de webhook para su validación, lo que completa el establecimiento de la confianza mutua.
De forma predeterminada, Dialogflow presenta un certificado de cliente emitido por
SSL.com (CN=Google LLC).
Solicita mTLS
Para solicitar una mTLS, sigue estos pasos:
- Prepara tu servidor HTTPS de webhook para que solicite el certificado de cliente durante el protocolo de enlace TLS.
- Configura el almacén de confianza de mTLS de tu servidor de webhook para que confíe en el certificado raíz de la autoridad de certificación raíz RSA de SSL.com, que puedes descargar directamente desde SSL.com:
- CA raíz:
SSL.com Root Certification Authority RSA - Huella digital 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 - Profundidad de verificación: Establece la profundidad de verificación del certificado de cliente TLS
en al menos
2. Dialogflow envía automáticamente el certificado intermedio (SSL.com Client Certificate Intermediate CA RSA R2) durante el protocolo de enlace TLS, por lo que solo necesitas agregar la AC raíz a tu almacén de confianza.
- CA raíz:
Configura tu servidor de webhook para que verifique el certificado de cliente cuando lo reciba. Si tu servidor o API Gateway incluye en la lista de entidades permitidas los certificados de cliente por asunto o nombre común (CN), permite los siguientes atributos de certificado (el certificado no incluye una extensión de nombre alternativo del sujeto [SAN]):
- Asunto:
C=US, ST=California, L=Mountain View, O=Google, OU=Applied Ai, CN=Google LLC - Emisor:
C=US, ST=Texas, L=Houston, O=SSL Corp, CN=SSL.com Client Certificate Intermediate CA RSA R2
Para una validación más sólida, haz coincidir el asunto y la entidad emisora completos, en lugar de solo
CN.- Asunto:
Llamada de ejemplo a un servidor de webhook con mTLS
En este ejemplo, se usa el agente que se muestra en la guía de inicio rápido con un servidor de
webhook
que ejecuta
openssl.
- Configuración de ejemplo
- Un agente de Dialogflow CX que toma pedidos de camisetas y los envía a un webhook que apunta a un servidor web independiente.
- Una clave privada para la comunicación TLS en un archivo llamado
key.pem. - Una cadena de certificados firmada por una
AC (autoridad certificadora)
de confianza pública en un archivo llamado
fullchain.pem. - El certificado raíz de SSL.com en un archivo llamado
SSLcomRootCertificationAuthorityRSA.pem, descargado de SSL.com.
-
Ejecuta el programa
openssl s_serveren la máquina del servidor.sudo openssl s_server -key key.pem -cert fullchain.pem -CAfile SSLcomRootCertificationAuthorityRSA.pem -accept 443 -verify 2 - Se envía una solicitud al agente desde una máquina cliente. En este ejemplo, la solicitud es "Quiero comprar una camisa roja grande". Esta solicitud se puede enviar con la consola de Dialogflow o a través de una llamada a la API.
-
Resultado de
openssl s_serveren la máquina del servidor.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
Certificado de cliente personalizado
Los certificados de cliente personalizados se pueden configurar a nivel de agente para que los usen todos los webhooks. En el momento de la invocación del webhook, los certificados configurados se presentarán durante el protocolo de enlace.
La clave privada y la frase de contraseña se configuran como un recurso de Secret Manager. Se le deberán otorgar permisos de descriptor de acceso a secretos de Secret Manager al agente de servicio de Dialogflow para que acceda al secreto.
Los certificados de cliente deben estar firmados por una autoridad certificadora para que el protocolo de enlace se realice correctamente.
Práctica recomendada
Para asegurarte de que las solicitudes de webhook se inicien desde tus propios agentes de Dialogflow, debes verificar el token de identidad de la cuenta de servicio del portador desde el encabezado de autorización de la solicitud. Como alternativa, puedes verificar un parámetro de sesión proporcionado anteriormente por un servidor de autenticación de tu lado.
Errores
Si la validación del certificado de cliente falla (por ejemplo, el servidor de webhook no confía en el certificado de cliente), el protocolo de enlace TLS falla y la sesión finaliza.
Mensajes de error comunes:
| Mensaje de error | Explicación |
|---|---|
| No se pudo verificar el certificado de cliente: x509: certificado firmado por autoridad desconocida | Dialogflow envía su certificado de cliente al webhook externo, pero el webhook externo no puede verificarlo. Asegúrate de que el almacén de confianza de tu webhook incluya el certificado raíz RSA de la autoridad de certificación raíz de SSL.com y de que la profundidad de verificación de tu servidor sea de al menos 2. |