Autenticação TLS mútua

O tráfego de rede iniciado pelo Dialogflow para solicitações de webhook é enviado em uma rede pública. Para garantir que o tráfego seja seguro e confiável em ambas as direções, o Dialogflow é compatível com a autenticação TLS mútua (mTLS) (em inglês). Durante o handshake de TLS padrão do Dialogflow, seu servidor de webhook apresenta um certificado que pode ser validado pelo Dialogflow, seguindo a cadeia de autoridade certificadora ou comparando o certificado com um certificado de CA personalizado. Ao ativar o mTLS no servidor de webhook, ele pode autenticar o certificado do cliente apresentado pelo Dialogflow ao servidor de webhook para validação, concluindo o estabelecimento de confiança mútua.

Por padrão, o Dialogflow apresenta um certificado do cliente emitido por SSL.com (CN=Google LLC).

Como solicitar mTLS

Para solicitar mTLS:

  1. Prepare o servidor HTTPS de webhook para solicitar o certificado do cliente durante o handshake de TLS.
  2. Configure o repositório de confiança mTLS do servidor de webhook para confiar no certificado raiz da autoridade certificadora raiz RSA do SSL.com, que pode ser baixado diretamente do SSL.com:
    • CA raiz: SSL.com Root Certification Authority RSA
    • Impressão 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
    • Profundidade de verificação: defina a profundidade de verificação do certificado do cliente TLS como pelo menos 2. O Dialogflow envia automaticamente o certificado intermediário (SSL.com Client Certificate Intermediate CA RSA R2) durante o handshake de TLS. Portanto, você só precisa adicionar a CA raiz ao seu repositório de confiança.
  3. Configure o servidor de webhook para verificar o certificado do cliente ao recebê-lo. Se o servidor ou gateway de API permitir certificados do cliente por assunto ou nome comum (CN, na sigla em inglês), permita os seguintes atributos de certificado (o certificado não inclui uma extensão de nome alternativo do sujeito (SAN, na sigla em inglês)):

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

    Para uma validação mais forte, faça a correspondência entre o assunto completo e o emissor, em vez de apenas CN.

Exemplo de chamada para um servidor de webhook usando mTLS

Este exemplo usa o agente mostrado no guia de início rápido com um servidor de webhook executando openssl.

  1. Exemplo de configuração
    1. Um agente de CX do Dialogflow CX que recebe pedidos de camisetas e os envia para um webhook que aponta para um servidor da Web independente.
    2. Uma chave privada para comunicação TLS em um arquivo chamado key.pem.
    3. Uma cadeia de certificados assinada por uma autoridade certificadora (CA) publicamente confiável em um arquivo chamado fullchain.pem.
    4. O certificado raiz do SSL.com em um arquivo chamado SSLcomRootCertificationAuthorityRSA.pem, baixado de SSL.com.
  2. Execute o programa openssl s_server na máquina do servidor.
    sudo openssl s_server -key key.pem -cert fullchain.pem -CAfile SSLcomRootCertificationAuthorityRSA.pem -accept 443 -verify 2
  3. Uma solicitação é enviada ao agente por uma máquina cliente. Neste exemplo, o pedido é "Quero comprar uma camisa vermelha grande". Essa solicitação pode ser enviada usando o console do Dialogflow ou por uma chamada de API.
  4. Saída de openssl s_server na máquina do 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 do cliente personalizado

Os certificados do cliente personalizados podem ser configurados no nível do agente para serem usados por todos os webhooks. No momento da invocação do webhook, os certificados configurados serão apresentados durante o handshake.

A chave privada e a senha longa são configuradas como um recurso do Secret Manager. O agente de serviço do Dialogflow precisa receber permissões de acessador de secrets do Secret Manager para o secret.

Os certificados do cliente precisam ser assinados por uma autoridade certificadora para que o handshake seja bem-sucedido.

Prática recomendada

Para garantir que as solicitações de webhook sejam iniciadas pelos seus próprios agentes do Dialogflow, verifique o token de identidade de serviço do Bearer no cabeçalho de autorização da solicitação. Como alternativa, é possível verificar um parâmetro de sessão fornecido anteriormente por um servidor de autenticação do seu lado.

Erros

Se a validação do certificado do cliente falhar (por exemplo, o servidor de webhook não confiar no certificado do cliente), o handshake de TLS falhará e a sessão será encerrada.

Mensagens de erro comuns:

Mensagem de erro Explicação
Falha ao verificar o certificado do cliente: x509: certificado assinado por autoridade desconhecida O Dialogflow envia seu certificado de cliente para o webhook externo, mas o webhook não pode verificá-lo. Verifique se o repositório de confiança do webhook inclui o certificado raiz RSA da autoridade certificadora raiz do SSL.com e se a profundidade de verificação do servidor é de pelo menos 2.