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 il TLS handshake standard di Dialogflow, il server webhook presenta un certificato che può essere convalidato da Dialogflow, seguendo la catena dell'autorità di certificazione o confrontando il certificato con un certificato CA personalizzato. Se abiliti mTLS sul tuo server webhook, questo può autenticare il certificato client presentato da Dialogflow al tuo server webhook per la convalida, completando l'instaurazione della fiducia reciproca.
Per impostazione predefinita, Dialogflow presenta un certificato client emesso da SSL.com (CN=Google LLC).
Richiesta di mTLS
Per richiedere mTLS:
- Prepara il server HTTPS del webhook per richiedere il certificato client durante il TLS handshake.
- Configura l'archivio di attendibilità mTLS del server webhook in modo che consideri attendibile il certificato radice SSL.com Root Certification Authority RSA, che puoi scaricare direttamente da SSL.com:
- CA radice:
SSL.com Root Certification Authority RSA - Impronta 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 - Profondità di verifica: imposta la profondità di verifica del certificato client TLS su almeno
2. Dialogflow invia automaticamente il certificato intermedio (SSL.com Client Certificate Intermediate CA RSA R2) durante il TLS handshake, quindi devi solo aggiungere la CA principale al tuo archivio di attendibilità.
- CA radice:
Configura il server webhook in modo che verifichi il certificato client al momento della ricezione. Se il tuo server o API Gateway inserisce nella lista consentita i certificati client in base al soggetto o al nome comune (CN), consenti i seguenti attributi del certificato (il certificato non include un'estensione del nome alternativo del soggetto (SAN)):
- Oggetto:
C=US, ST=California, L=Mountain View, O=Google, OU=Applied Ai, CN=Google LLC - Emittente:
C=US, ST=Texas, L=Houston, O=SSL Corp, CN=SSL.com Client Certificate Intermediate CA RSA R2
Per una convalida più efficace, abbina sia l'oggetto completo sia l'emittente, anziché solo
CN.- Oggetto:
Esempio di chiamata a un server webhook utilizzando mTLS
Questo esempio utilizza l'agente mostrato nella guida rapida con un server webhook che esegue openssl.
- Configurazione di esempio
- Un agente Dialogflow CX che accetta ordini di magliette e li invia a un webhook che rimanda a un server web autonomo.
- Una chiave privata per la comunicazione TLS in un file denominato
key.pem. - Una catena di certificati firmata da un'autorità di certificazione (CA) attendibile pubblicamente in un file denominato
fullchain.pem. - Il certificato radice SSL.com in un file denominato
SSLcomRootCertificationAuthorityRSA.pem, scaricato da SSL.com.
-
Esegui il programma
openssl s_servernella macchina server.sudo openssl s_server -key key.pem -cert fullchain.pem -CAfile SSLcomRootCertificationAuthorityRSA.pem -accept 443 -verify 2 - Viene inviata una richiesta all'agente da un computer client. In questo esempio, la richiesta è "Voglio acquistare una camicia rossa grande". Questa richiesta può essere inviata utilizzando la console Dialogflow o tramite una chiamata API.
-
Output di
openssl s_servernella macchina server.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
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. All'agente di servizio Dialogflow dovranno essere concesse le autorizzazioni Secret Manager Secret Accessor per il secret.
Affinché l'handshake vada a buon fine, i certificati client devono essere firmati da un'autorità di certificazione.
Best practice
Per assicurarti che le richieste di webhook vengano avviate dai tuoi agenti Dialogflow, devi verificare il token di identità del servizio Bearer dall'intestazione Authorization della richiesta. In alternativa, puoi verificare un parametro di sessione fornito in precedenza da un server di autenticazione da parte tua.
Errori
Se la convalida del certificato client non va a buon fine (ad esempio, il server webhook non considera attendibile il certificato client), il TLS handshake non va a buon fine e la sessione termina.
Messaggi di errore comuni:
| Messaggio di errore | Spiegazione |
|---|---|
| Impossibile verificare il certificato del client: x509: certificato firmato da un'autorità sconosciuta | Dialogflow invia il proprio certificato client al webhook esterno, ma quest'ultimo non può verificarlo. Assicurati che l'archivio di attendibilità del webhook includa il certificato radice RSA dell'autorità di certificazione radice SSL.com e che la profondità di verifica del server sia almeno 2. |