Configurare la sicurezza del canale Web e Direct Line

Quando crei un agente di Copilot Studio, chiunque conosca l'ID agente può accedere immediatamente all'agente tramite il sito Web Demo e il sito web personalizzato. Questi canali sono disponibili per impostazione predefinita e non è necessaria alcuna configurazione.

Per l'app Microsoft Teams, è possibile configurare opzioni avanzate di sicurezza del canale Web.

Note

Se hai una licenza solo per Teams, non è possibile generare i segreti per abilitare l'accesso sicuro. I token di accesso sicuro vengono creati automaticamente per te e l'accesso sicuro è abilitato per impostazione predefinita.

Gli utenti possono trovare l'ID agente direttamente da Copilot Studio o ricevendolo da un utente. Tuttavia, a seconda della capacità e della sensibilità dell'agente, l'accesso potrebbe non essere auspicabile.

Usando la sicurezza basata su Direct Line, è possibile abilitare l'accesso solo alle posizioni controllate abilitando l'accesso protetto con segreti o token Direct Line.

Puoi anche scambiare e rigenerare segreti e aggiornare i token e puoi facilmente disabilitare l'accesso protetto se non vuoi più usarlo.

Note

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

Abilitare o disabilitare la sicurezza del canale 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.

  1. Attivare Richiedi accesso protetto.

Avvertimento

Quando si attiva o si disattiva Richiedi accesso protetto, possono essere necessarie fino a due ore prima che il sistema propaga le impostazioni e venga applicato. 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.

Se è necessario disabilitare l'opzione di sicurezza del canale Web, è possibile farlo deselezionando l'interruttore Richiedi accesso protetto . La propagazione della disabilitazione dell'accesso protetto può richiedere fino a due ore.

Screenshot di un messaggio di conferma quando si disabilita l'accesso protetto, che indica che questa azione rende disponibile il sito web Demo e qualsiasi canale Direct Line che non utilizza un segreto o un token. Questa azione può richiedere fino a due ore per avere effetto.

Usare segreti o token

Se stai creando un'app da servizio a servizio, specificare il segreto nelle richieste di intestazione di autorizzazione potrebbe essere l'approccio più semplice.

Se stai scrivendo un'app in cui il client viene eseguito in un browser Web o un'app per dispositivi mobili oppure un codice altrimenti visibile al cliente, 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.

Avvertimento

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 di intestazione di autorizzazione della tua app o richieste 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. Selezionare l'icona di visibilità per visualizzare il segreto. Viene visualizzato un messaggio di avviso prima di poterlo svelare.

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.

Rigenerare un segreto

Per rigenerare un segreto, seleziona Rigenera vicino al segreto.

Avvertimento

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

Generare un token

È possibile generare un token usato all'avvio di una singola conversazione dell'agente. Per altre informazioni, vedere la sezione Get Direct Line token in Pubblicare un agente in app per dispositivi mobili o personalizzate.

  1. Ottieni il segreto.

  2. Nel codice del servizio inviare la richiesta seguente per scambiare il segreto per un token. Sostituisci <SECRET> con il valore del segreto ottenuto nel passaggio 1.

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

I seguenti frammenti forniscono esempi della richiesta del token generato e della sua risposta.

Esempio di richiesta di generazione del token

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

Esempio di risposta di generazione del token

HTTP/1.1 200 OK
[other headers]

{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "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.

Aggiornare un token

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

Non è possibile aggiornare un token scaduto.

Per aggiornare un token, inviare la richiesta seguente e sostituire <TOKEN TO BE REFRESHED> con il token da aggiornare.

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer <TOKEN TO BE REFRESHED>

I seguenti frammenti forniscono esempi della richiesta di aggiornamento del token e della risposta.

Esempio di richiesta di aggiornamento

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

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": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}

Per altre informazioni sull'aggiornamento di un token, vedere la sezione Refresh a Direct Line token in Direct Line API - Authentication.

Contenuti correlati

  • Last updated on