Condividi tramite

Configurare la sicurezza del canale Web e Direct Line

  • Articolo

Quando crei un Copilot Studio agente, questo è immediatamente disponibile nei canali Sito web demo e Sito web personalizzato per chiunque conosca l'ID agente. Questi canali sono disponibili per impostazione predefinita e non è necessaria alcuna configurazione.

Puoi configurare le opzioni di sicurezza del canale Web avanzate per l'app Microsoft Teams.

Nota

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 dall'interno Copilot Studio o ricevendolo da qualcuno. Tuttavia, a seconda delle capacità di agente e di importanza, ciò potrebbe non essere auspicabile.

Con la sicurezza basata su Direct Line puoi consentire l'accesso solo alle posizioni che controlli 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.

Nota

Copilot Studio usa il Bot Framework Direct Line canale per Connetti la tua pagina web o app su agente.

Abilitare o disabilitare la sicurezza del canale Web

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

Una volta abilitata questa opzione, i canali hanno bisogno che il client autentichi le richieste tramite un segreto o un token generato utilizzando il segreto, ottenuto in fase di esecuzione.

Qualsiasi accesso a agente che non fornisca questa misura di sicurezza non funzionerà.

  1. Sotto agente, sotto Impostazioni, Seleziona Sicurezza. Quindi seleziona il riquadro Sicurezza canale Web.

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

  2. Imposta l'interruttore Richiedi accesso protetto su Abilitato.

    Schermata che mostra la pagina di sicurezza del canale Web.

Avviso

Una volta abilitato o disabilitato "Richiedi accesso protetto", il sistema può impiegare fino a due ore per propagare le impostazioni e renderle effettive. Fino ad allora, sarà attiva l'impostazione precedente. Non è necessario pubblicare agente affinché questa modifica abbia effetto.

Dovresti pianificare in anticipo per evitare di esporre involontariamente il tuo agente.

Se è necessario disabilitare l'opzione di sicurezza del canale Web, è possibile farlo impostando Richiedi accesso protetto su Disabilitato. La disattivazione dell'accesso protetto può richiedere fino a due ore per propagarsi.

Screenshot che mostra un messaggio di conferma quando si disabilita l'accesso protetto, che dice che questa azione esegue il rendering del sito Web demo e di qualsiasi canale Direct Line che non utilizza un segreto o un token disponibile. Questa azione può richiedere fino a due ore per diventare effettiva.

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.

Avviso

Sconsigliamo vivamente di esporre il segreto in qualsiasi codice eseguito nel browser, hardcoded o trasferito tramite chiamata di rete.

Acquisire il token utilizzando il segreto nel codice del tuo servizio è il modo più sicuro per proteggere il tuo Copilot Studio agente.

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. Seleziona l'icona di visibilità Icona Visibilità. per svelare il segreto. Viene visualizzato un messaggio di avviso prima di poterlo svelare.

Scambiare segreti

Se hai bisogno di cambiare il segreto utilizzato dal tuo agente, puoi farlo senza alcuna interruzione o tempi di inattività.

Copilot Studio ti fornisce due segreti che funzionano simultaneamente. Puoi scambiare il segreto utilizzato con l'altro. Una volta che i segreti sono stati scambiati e i tuoi utenti sono tutti connessi utilizzando il nuovo segreto, puoi rigenerare il segreto.

Rigenerare un segreto

Per rigenerare un segreto, seleziona Rigenera vicino al segreto.

Avviso

Qualsiasi utente connesso tramite il segreto originale o con un token ottenuto da quel segreto verrà disconnesso.

Generare un token

Puoi generare un token che può essere utilizzato quando avvii una singola conversazione agente. Per ulteriori informazioni, consulta la sezione Ottieni Direct Line token in Pubblica un agente su app mobili o personalizzate.

  1. Ottieni il segreto.

  2. Effettua la seguente richiesta nel codice del servizio per scambiare il segreto con 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.

Perché il token rimanga utile, è necessario aggiornare il token prima che scada.

Aggiornare un token

Un token può essere aggiornato un numero illimitato di volte, a condizione che non sia scaduto.

Un token scaduto non può essere aggiornato.

Per aggiornare un token, effettua la seguente richiesta e sostituisci <TOKEN TO BE REFRESHED> con il token che desideri 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.

Perché il nuovo token rimanga utile, è necessario aggiornare di nuovo il token prima che scada.

HTTP/1.1 200 OK
[other headers]

{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}

Per ulteriori informazioni sull'aggiornamento di un token, vedi la sezione Aggiornare un token Direct Line in API Direct Line - Autenticazione.

Contenuto correlato