Configurare la sicurezza del canale Web e Direct Line

La sicurezza dei canali Web e Direct Line controlla se i client devono fornire un segreto o token Direct Line per collegarsi al tuo agente di Copilot Studio. Senza accesso sicuro, chiunque conosca l'ID dell'agente può connettersi tramite i canali del sito Demo e del sito Custom.

Note

Nella modalità solo Teams, non puoi generare chiavi segrete. I token di accesso sicuro vengono creati automaticamente e l'accesso sicuro è attivo di default. Per i requisiti di licenza, consulta i Microsoft Product Terms.

Attiva Richiedi accesso sicuro per richiedere ai clienti di presentare un segreto o un token. Queste credenziali autorizzano l'accesso al canale Direct Line; non autenticano l'utente finale né limitano l'accesso a un sito web specifico da sole. Configura l'autenticazione degli utenti separatamente quando gli utenti devono effettuare il login.

Puoi sostituire e rigenerare segreti, aggiornare token o disattivare l'accesso sicuro quando non è più necessario.

Copilot Studio usa il canale Direct LineBot Framework per connettere la pagina Web o l'app all'agente.

Attiva o disattiva la sicurezza dei canali web

È possibile imporre l'uso di segreti e token per ogni singolo agente.

Quando si attiva questa opzione, i canali richiedono al client di autenticare le richieste usando un segreto o usando un token generato usando il segreto ottenuto in fase di esecuzione.

I tentativi di accesso all'agente che non forniscono questa misura di sicurezza non funzionano.

  1. Passare alla pagina Impostazioni per l'agente, selezionare Sicurezza e quindi selezionare Sicurezza canale Web.

    Screenshot che mostra la sicurezza del canale Web evidenziata nel riquadro a comparsa Impostazioni.

  2. Attivare Richiedi accesso protetto.

Warning

Quando attivi o disattivi Richiedi accesso protetto, possono volerci fino a due ore prima che le nuove impostazioni di sistema entrino in vigore. Fino ad allora, l'impostazione precedente è attiva. Non è necessario pubblicare l'agente per rendere effettiva questa modifica.

Pianificare in anticipo per evitare di esporre l'agente in modo involontario.

Per disattivare la sicurezza del canale web, disattiva Richiedi accesso sicuro e conferma la modifica. Il cambiamento può richiedere fino a due ore per fare effetto.

Screenshot della conferma che disattivare l'accesso protetto rende disponibili il sito dimostrativo e i canali Direct Line non sicuri.

Usare segreti o token

Per un'app service-to-service, specifica il segreto nell'intestazione di autorizzazione delle richieste dal tuo servizio.

Se stai scrivendo un'app in cui il client viene eseguito in un browser Web o un'app per dispositivi mobili, oppure se il codice potrebbe essere visibile ai clienti, devi scambiare il tuo segreto con un token. Se non usi un token, il tuo segreto può essere compromesso. Quando effettui la richiesta per acquisire il token nel tuo servizio, specifica il segreto nell'intestazione dell'autorizzazione.

I token funzionano solo per una singola conversazione e scadono se non aggiornati.

Scegli il modello di sicurezza che funziona meglio per la tua situazione.

Warning

Non esporre il segreto in alcun codice eseguito nel browser, codificato in modo fisso o trasferito attraverso una chiamata di rete.

L'acquisizione del token usando la chiave segreta nel codice del servizio è il modo più sicuro per proteggere l'agente di Copilot Studio.

Ottenere i segreti

Hai bisogno del segreto in modo da poterlo specificare nelle richieste con l'header di autorizzazione della tua app o simili.

  1. Nel menu di navigazione, in Impostazioni seleziona Sicurezza. Quindi seleziona il riquadro Sicurezza canale Web.

  2. Seleziona Copia per Segreto 1 o Segreto 2 per copiarlo negli appunti. Per rivelare il segreto, seleziona l'icona di visibilità e rivedi il prompt di avviso.

Scambiare segreti

Se è necessario modificare il segreto usato dall'agente, è possibile modificarlo senza tempi di inattività o interruzioni.

Copilot Studio offre due segreti, che funzionano contemporaneamente. È possibile scambiare il segreto usato dall'agente con l'altro. Dopo che i segreti vengono scambiati e gli utenti sono tutti connessi usando il nuovo segreto, è possibile rigenerare il segreto.

Rigenera un segreto

Per rigenerare un segreto, seleziona Rigenera vicino al segreto.

Warning

Il profilo utente che si connette utilizzando il segreto originale o un token ottenuto da tale segreto viene disconnesso.

Generare un token

Puoi generare un token per avviare una conversazione con un singolo agente. Questa procedura scambia un segreto Direct Line con un token di conversazione nel tuo codice di servizio. Per l'opzione endpoint del token Copilot Studio, scopri di più su Get Direct Line token.

  1. Ottieni il segreto.

  2. Nel tuo codice di servizio, invia la richiesta di generazione di token di esempio. Sostituisci <DirectLineSecret> con il segreto che hai copiato.

Esempio di richiesta di generazione del token

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer <DirectLineSecret>

Esempio di risposta di generazione del token

HTTP/1.1 200 OK
[other headers]
{
  "conversationId": "abc123",
  "token": "<DirectLineToken>",
  "expires_in": 1800
}

Se la richiesta ha esito positivo, la risposta contiene un token valido per una conversazione e un valore expires_in che indica il numero di secondi alla scadenza del token.

Per mantenere utile il token, è necessario aggiornare il token prima della scadenza.

Aggiorna un token

È possibile aggiornare un token un numero illimitato di volte, purché non sia scaduto.

Non è possibile aggiornare un token scaduto.

Invia la richiesta di aggiornamento del campione. Sostituisci <DirectLineToken> con il token non scaduto che vuoi aggiornare. Usa il token della conversazione, non il segreto di Direct Line.

Esempio di richiesta di aggiornamento

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer <DirectLineToken>

Esempio di risposta di aggiornamento

Se la richiesta ha esito positivo, la risposta contiene un nuovo token valido per la stessa conversazione del token precedente e un valore expires_in che indica il numero di secondi alla scadenza del nuovo token.

Per mantenere utile il nuovo token, aggiornare di nuovo il token prima della scadenza.

HTTP/1.1 200 OK
[other headers]
{
  "conversationId": "abc123",
  "token": "<DirectLineToken>",
  "expires_in": 1800
}

Scopri di più in Aggiornare un token Direct Line.