Autenticación mutua de TLS

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:

  1. Prepara tu servidor HTTPS de webhook para que solicite el certificado de cliente durante el protocolo de enlace TLS.
  2. 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.
  3. 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.

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.

  1. Configuración de ejemplo
    1. Un agente de Dialogflow CX que toma pedidos de camisetas y los envía a un webhook que apunta a un servidor web independiente.
    2. Una clave privada para la comunicación TLS en un archivo llamado key.pem.
    3. Una cadena de certificados firmada por una AC (autoridad certificadora) de confianza pública en un archivo llamado fullchain.pem.
    4. El certificado raíz de SSL.com en un archivo llamado SSLcomRootCertificationAuthorityRSA.pem, descargado de SSL.com.
  2. Ejecuta el programa openssl s_server en la máquina del servidor.
    sudo openssl s_server -key key.pem -cert fullchain.pem -CAfile SSLcomRootCertificationAuthorityRSA.pem -accept 443 -verify 2
  3. 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.
  4. Resultado de openssl s_server en 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.