Autenticazione TLS reciproca

Il traffico di rete avviato da Dialogflow per le richieste webhook viene inviato su una rete pubblica. Per garantire che il traffico sia sicuro e attendibile in entrambe le direzioni, Dialogflow supporta facoltativamente l'autenticazione TLS reciproca (mTLS). Durante l'handshake TLS standard di Dialogflow, il server webhook presenta un certificato che può essere convalidato da Dialogflow, seguendo la catena di autorità di certificazione o confrontando il certificato con un certificato CA personalizzato. Se abiliti mTLS sul server webhook, questo potrà autenticare il certificato Google presentato da Dialogflow al server webhook per la convalida, completando la creazione di una fiducia reciproca.

Richiesta di mTLS

Per richiedere mTLS:

1. Prepara il server HTTPS del webhook per richiedere il certificato client durante l'handshake TLS.
2. Il server webhook deve verificare il certificato client al momento della ricezione.
3. Installa una catena di certificati per il server webhook, che può essere considerato attendibile sia dal client che dal server. Le applicazioni che si connettono ai servizi Google devono considerare attendibili tutte le autorità di certificazione elencate da Google Trust Services. Puoi scaricare i certificati radice da: https://pki.goog/.

Chiamata di esempio a un server webhook utilizzando mTLS

Questo esempio utilizza l'agente mostrato nella guida rapida con un server webhook in esecuzione su openssl.

1. Configurazione di esempio
   1. Un agente Dialogflow CX che riceve ordini di magliette e li invia a un webhook che punta a un server web autonomo.
   2. Una chiave privata per la comunicazione TLS in un file denominato key.pem.
   3. Una catena di certificati firmata da un'autorità di certificazione (CA) attendibile pubblicamente in un file denominato fullchain.pem.
2. Esegui il programma openssl s_server nella macchina server.

   sudo openssl s_server -key key.pem -cert fullchain.pem -accept 443 -verify 1

3. Una richiesta viene inviata all'agente da una macchina client. Per questo esempio, la richiesta è "Voglio acquistare una maglietta rossa taglia large". Questa richiesta può essere inviata utilizzando la console Dialogflow o tramite una chiamata API.
4. Output di openssl s_server nella macchina server.

   verify depth is 1
   Using default temp DH parameters
   ACCEPT
   depth=2 C = US, O = Google Trust Services LLC, CN = GTS Root R1
   verify return:1
   depth=1 C = US, O = Google Trust Services LLC, CN = GTS CA 1D4
   verify return:1
   depth=0 CN = *.dialogflow.com
   verify return:1
   -----BEGIN SSL SESSION PARAMETERS-----
   MII...
   -----END SSL SESSION PARAMETERS-----
   Client certificate
   -----BEGIN CERTIFICATE-----
   MII...
   -----END CERTIFICATE-----
   subject=CN = *.dialogflow.com
   
   issuer=C = US, O = Google Trust Services LLC, CN = GTS CA 1D4
   
   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
         

Certificato client personalizzato

I certificati client personalizzati possono essere configurati a livello di agente per essere utilizzati da tutti i webhook. Al momento della chiamata del webhook, i certificati configurati verranno presentati durante l'handshake.

La chiave privata e la passphrase sono configurate come risorsa Secret Manager. Al service agent Dialogflow dovranno essere concesse le autorizzazioni di accesso ai secret di Secret Manager per il secret.

I certificati client devono essere firmati da un'autorità di certificazione per la riuscita dell'handshake.

Best practice

Per assicurarti che le richieste webhook vengano avviate dai tuoi agenti Dialogflow, devi verificare il token di identità del servizio dall'intestazione Authorization della richiesta. In alternativa, puoi verificare un parametro di sessione fornito in precedenza da un server di autenticazione dalla tua parte.

Errori

Se la convalida del certificato client non riesce (ad esempio, il server webhook non considera attendibile il certificato client), l'handshake TLS non riesce e la sessione termina.

Messaggi di errore comuni:

Messaggio di errore	Spiegazione
Impossibile verificare il certificato del client: x509: certificate signed by unknown authority	Dialogflow invia il certificato client al webhook esterno, ma quest'ultimo non può verificarlo. Ciò potrebbe essere dovuto al fatto che il webhook esterno non ha installato correttamente la catena CA. Tutte le CA radice di Google devono essere attendibili.