Abilitare il rilevamento e la protezione delle minacce esterne per gli agenti personalizzati di Copilot Studio (anteprima)

[Questo articolo fa parte della documentazione non definitiva, pertanto è soggetto a modifiche.]

Gli agenti personalizzati creati in Copilot Studio sono protetti per impostazione predefinita. Includono una protezione integrata contro varie minacce, come gli attacchi di injection del prompt utente (UPIA) e gli attacchi di injection del prompt cross-domain (XPIA). Durante l'esecuzione, l'agente blocca attacchi di questo tipo, riducendo il rischio di esfiltrazione dei dati.

Per aumentare ulteriormente le funzionalità di monitoraggio e la sicurezza degli agenti personalizzati, Copilot Studio consente alle organizzazioni di configurare sistemi di rilevamento delle minacce esterni per una supervisione avanzata. Questi strumenti operano durante il runtime dell'agente, valutando continuamente l'attività dell'agente. Se il sistema rileva strumenti o azioni sospetti, può intervenire per impedirne l'esecuzione. Questo rilevamento delle minacce offre un livello aggiuntivo di protezione in tempo reale e applicazione della conformità.

Importante

Il rilevamento delle minacce esterne viene chiamato solo su agenti generativi che usano l'orchestrazione generativa. Il rilevamento delle minacce esterne viene ignorato per gli agenti classici.

Funzionamento

Un sistema esterno di rilevamento minacce è configurato come servizio Web, esponendo un'API REST con un endpoint di rilevamento minacce. Viene configurata una connessione sicura tra l'agente e l'endpoint. Durante l'esecuzione, ogni volta che l'orchestratore considera di invocare uno strumento, invia dati rilevanti sull'uso dello strumento proposto all'endpoint di rilevamento delle minacce per la valutazione. Il sistema di rilevamento delle minacce analizza i dati e restituisce una decisione se consentire o bloccare l'invocazione dello strumento.

Se il sistema di rilevamento delle minacce rileva un problema di sicurezza durante l'operazione di un agente, l'agente arresta immediatamente l'elaborazione e notifica all'utente che il messaggio è bloccato. Se invece il sistema approva l'operazione, l'agente continua senza interruzioni, senza alcun effetto visibile o interruzione per l'utente.

Importante

Questo articolo contiene la documentazione sull'anteprima di Microsoft Copilot Studio ed è pertanto soggetto a modifiche.

Le funzionalità di anteprima non sono destinate a essere utilizzate per la produzione e sono soggette a restrizioni. Queste funzionalità sono disponibili prima di una versione ufficiale in modo che sia possibile ottenere l'accesso iniziale e inviare commenti.

Se stai creando un agente destinato alla produzione, vedi Panoramica di Microsoft Copilot Studio.

Opzioni per la configurazione del rilevamento delle minacce esterne

Copilot Studio supporta un approccio flessibile "Bring Your Own Protection". Le organizzazioni hanno la libertà di integrare soluzioni di sicurezza che meglio soddisfano i propri requisiti specifici.

Le opzioni includono:

• Sviluppa strumenti di monitoraggio personalizzati oppure affidane lo sviluppo a terzi. Per maggiori informazioni su come configurare l'endpoint di sistema affinché il tuo agente possa connettersi, vedi Creare un sistema di rilevamento delle minacce in tempo reale per gli agenti di Copilot Studio
• Applica una soluzione aziendale robusta grazie a Microsoft Defender
• Usa prodotti di altri fornitori di sicurezza affidabili

Quali dati sono condivisi con il provider di rilevamento delle minacce?

Una volta configurata una connessione a un sistema di rilevamento minacce, l'agente condivide dati con il fornitore di sicurezza esterno durante la sua esecuzione. L'agente comunica con il servizio ogni volta che considera di invocare uno strumento. Questa condivisione dei dati garantisce un processo decisionale efficiente dal sistema configurato, senza compromettere l'esperienza degli utenti dell'agente.

I dati di alto livello condivisi con il sistema includono:

• La richiesta recente dell'utente e la cronologia più recente dei messaggi di chat scambiati tra l'agente e l'utente.
• Output degli strumenti precedenti usati dall'agente.
• Metadati della conversazione: identità dell'agente, identità dell'utente che interagisce con l'agente, tenant dell'utente e trigger che ha attivato l'agente (se applicabile).
• Lo strumento che l'agente vuole invocare, incluso il ragionamento generato dall'agente sul motivo della selezione di questo strumento e gli input e i valori proposti.

Importante

• I criteri di gestione dei dati del provider potrebbero essere diversi dai criteri usati da Microsoft. Le differenze potrebbero includere l'elaborazione e la memorizzazione dei dati al di fuori della propria area geografica.
• Devi assicurarti che il fornitore e le condizioni rispettino gli standard e le normative necessarie a proteggere i dati della tua organizzazione.
• Se vuoi bloccare la condivisione dei dati con il servizio di rilevamento minacce, puoi disconnettere l'integrazione in qualsiasi momento.

Prerequisiti

Prima di iniziare, è necessario disporre di quanto segue:

• Un servizio esterno di rilevamento delle minacce configurato per valutare le richieste di utilizzo degli strumenti da parte degli agenti. Il servizio deve esporre un endpoint API REST. Per la configurazione sul lato Copilot Studio dell'integrazione, serve l'URL di base del servizio Web del fornitore di sicurezza. In questo articolo ci si riferisce a questo URL come endpoint. L'agente invia richieste di rilevamento delle minacce alle API a questo URL base. Dovresti ricevere questo URL dal tuo provider di sicurezza.
• Un tenant Microsoft Entra dove puoi registrare un'applicazione per l'autenticazione tra l'agente e il servizio di rilevamento minacce.
• Un utente con il ruolo di amministratore di Power Platform per configurare una connessione tra l'agente e il sistema di rilevamento delle minacce esterno sia a livello di ambiente individuale sia a livello di gruppo di ambienti.

Configurare un sistema di rilevamento delle minacce esterno

Il processo per configurare un sistema di rilevamento delle minacce esterno per l'agente prevede due passaggi:

1. Configura un'applicazione Microsoft Entra.

2. Configura il rilevamento delle minacce nell'interfaccia di amministrazione di Power Platform.

Passaggio 1: configurare un'applicazione Microsoft Entra

Esistono due percorsi per configurare un'applicazione Microsoft Entra:

• Opzione A: configurare l'uso dello script di PowerShell (scelta consigliata)
• Opzione B: eseguire la configurazione manualmente tramite il portale di Azure

Opzione A: eseguire la configurazione con PowerShell (scelta consigliata)

Puoi utilizzare uno script PowerShell fornito per automatizzare la creazione e la configurazione della tua applicazione Microsoft Entra.

Prerequisiti per la configurazione PowerShell

• Windows PowerShell 5.1 o versione successiva
• Autorizzazioni sufficienti per creare registrazioni dell'applicazione nel tenant di Microsoft Entra
• L'URL di base del servizio Web di rilevamento delle minacce. L'URL è indicato come Endpoint nei parametri dello script seguenti. Dovresti ricevere questo URL dal tuo provider di sicurezza.
• L'ID tenant di Microsoft Entra dell'organizzazione. L'ID del tenant è indicato come TenantId nei parametri dello script seguenti.

Scaricare e preparare lo script

Scarica lo script Create-CopilotWebhookApp.ps1.

Parametri di script

Lo script accetta i parametri elencati di seguito:

Parametro	Type	Obbligatorio	Descrizione
TenantId	String	Sì	ID tenant di Microsoft Entra in formato GUID (ad esempio, 12345678-1234-1234-1234-123456789012).
Endpoint	String	Sì	URL di base per il servizio esterno di rilevamento minacce (fornito dal tuo provider di sicurezza). Se usi Microsoft Defender come fornitore di sicurezza, puoi ottenere l'endpoint dal portale Defender.
DisplayName	String	Sì	Nome visualizzato univoco che fornisci per la registrazione dell'applicazione. Può essere usato tra 1 e 120 caratteri.
FICName	String	Sì	Nome univoco fornito per le credenziali di identità federate. Può essere usato tra 1 e 120 caratteri.
DryRun	Switch	No	Flag opzionale. Quando il flag -DryRun è presente, lo script esegue una verifica senza creare risorse.

Eseguire lo script

Per creare l'applicazione:

1. Apri Windows PowerShell come amministratore.

2. Passa alla directory contenente lo script.

3. Esegui lo script seguente, sostituendo i valori del segnaposto per TenantId, Endpoint, DisplayName e FICName con parametri propri:

   .\Create-CopilotWebhookApp.ps1 `
   -TenantId "11111111-2222-3333-4444-555555555555" `
   -Endpoint "https://provider.example.com/threat_detection/copilot" `
   -DisplayName "Copilot Security Integration - Production" `
   -FICName "ProductionFIC"
   

Lo script interattivo viene eseguito nella riga di comando. Lo script restituisce l'ID dell'applicazione Microsoft Entra creata. Ti servirà l'ID dell'app in seguito, quando configurerai il rilevamento delle minacce nell'interfaccia di amministrazione di Power Platform.

Opzione B: eseguire la configurazione manualmente tramite il portale di Azure

Prerequisiti per la configurazione manuale

• L'ID tenant di Microsoft Entra dell'organizzazione. L'ID del tenant è indicato come tenantId nelle istruzioni che seguono.
• Autorizzazioni sufficienti per creare registrazioni dell'applicazione nel tenant di Microsoft Entra.
• L'URL di base del servizio Web di rilevamento minacce che stai usando. Questo è indicato come endpoint nelle istruzioni seguenti. Dovresti ricevere questo URL dal tuo provider di sicurezza.

Registrare un'applicazione Microsoft Entra

Segui questa procedura per creare una registrazione dell'applicazione Microsoft Entra. L'applicazione viene utilizzata per garantire l'autenticazione sicura tra l'agente e il servizio Web di rilevamento delle minacce. Vedi Registrare un'applicazione in Microsoft Entra ID per informazioni su come creare un'app di questo tipo.

1. Accedi al portale di Azure e passare alla pagina Microsoft Entra ID .

2. In Registrazioni app, seleziona Nuova registrazione.

3. Fornisci un nome e seleziona Account solo in questa directory dell'organizzazione (solo Contoso - Tenant singolo) come tipo di account supportato.

4. Registra l'app.

5. Dopo aver creato l'app, copia l'ID dell'app. Ti servirà l'ID dell'app in seguito, quando configurerai il rilevamento delle minacce nell'interfaccia di amministrazione di Power Platform.

Autorizza l'applicazione Microsoft Entra con il provider preferito

L'agente utilizza le Federated Identity Credentials (FIC) come metodo di autenticazione sicuro e senza segreti per lo scambio di dati con il fornitore del sistema di rilevamento delle minacce. Segui questa procedura per configurare FIC per l'applicazione Microsoft Entra. Per ulteriori informazioni, vedi Configurare un'identità gestita assegnata all'utente per ritenere attendibile un provider di identità esterno.

1. Apri il portale di Azure e vai a Registrazioni app. Seleziona l'applicazione creata nel passaggio 1 precedente.

2. Nella barra laterale, seleziona Gestisci>Certificati e segreti>Credenziali federate.

3. Seleziona Aggiungi credenziali.

4. Nell'elenco a discesa Scenario credenziali federate, seleziona Altro emittente.

5. Compila i campi in base alle istruzioni seguenti:

   • Autorità emittente: immetti l'URL seguente, sostituendo {tenantId} con l'ID tenant Microsoft Entra dell'organizzazione: https://login.microsoftonline.com/{tenantId}/v2.0

   • Tipo: seleziona Identificatore oggetto esplicito.

   • Valore: immetti una stringa strutturata come segue: /eid1/c/pub/t/{base 64 encoded tenantId}/a/m1WPnYRZpEaQKq1Cceg--g/{base 64 encoded endpoint}

     Esegui la codifica Base64 per l'ID tenant di Microsoft Entra della tua organizzazione e per l'URL di base del servizio Web di rilevamento delle minacce. Sostituisci il segnaposto {base 64 encoded tenantId} con il valore codificato in Base64 del tuo ID tenant e il segnaposto {base 64 encoded endpoint} con il valore codificato in Base64 dell'URL di base.

     Per ottenere la codifica Base64 del tuo ID tenant e dell'URL dell'endpoint, usa il seguente script PowerShell. Assicurati di sostituire i valori provvisori "1111111-2222-3333-4444-555555555555" e "https://provider.example.com/threat_detection/copilot" con i tuoi valori effettivi per l'ID del tenant e l'URL dell'endpoint:

     # Encoding tenant ID
     $tenantId = [Guid]::Parse("11111111-2222-3333-4444-555555555555")
     $base64EncodedTenantId = [Convert]::ToBase64String($tenantId.ToByteArray()).Replace('+','-').Replace('/','_').TrimEnd('=')
     Write-Output $base64EncodedTenantId
     
     # Encoding the endpoint
     $endpointURL = "https://provider.example.com/threat_detection/copilot"
     $base64EncodedEndpointURL = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($endpointURL)).Replace('+','-').Replace('/','_').TrimEnd('=')
     Write-Output $base64EncodedEndpointURL
     

   • Nome: scegli un nome descrittivo.

6. Selezionare il pulsante Aggiungi.

Passaggio 2: configurare il sistema di rilevamento delle minacce

Successivamente, devi configurare il sistema di rilevamento delle minacce nell'interfaccia di amministrazione di Power Platform per collegare il tuo agente al provider di sicurezza esterno.

Prerequisiti per configurare il rilevamento delle minacce nell'interfaccia di amministrazione di Power Platform

• L'ID app dell'applicazione Microsoft Entra che hai creato nel passaggio precedente.
• Il collegamento dell'endpoint fornito dal provider del tuo sistema di monitoraggio esterno. Il collegamento dell'endpoint è lo stesso URL di base dell'endpoint che utilizzi quando configuri l'applicazione Microsoft Entra.
• Un utente con un ruolo di amministratore Power Platform per configurare la connessione.
• Esegui eventuali altri passaggi richiesti dal tuo provider di sicurezza per autorizzare la tua applicazione registrata. Consulta la documentazione del tuo fornitore (se applicabile) per eventuali passaggi specifici di onboarding e autorizzazione.

Per configurare il sistema di rilevamento delle minacce nell'interfaccia di amministrazione di Power Platform, segui questi passaggi:

1. Accedi all'interfaccia di amministrazione di Power Platform.

2. Seleziona Sicurezza nel riquadro di spostamento laterale, quindi Rilevamento delle minacce. Si apre la pagina Rilevamento delle minacce.

3. Seleziona Rilevamento minacce aggiuntivo. Verrà aperto un riquadro.

4. Seleziona l'ambiente per cui vuoi migliorare la protezione degli agenti e seleziona Configura. Verrà aperto un riquadro.

5. Seleziona Consenti a Copilot Studio di condividere i dati con un provider di rilevamento delle minacce.

6. Nella sezione ID app Azure Entra, inserisci l'ID dell'applicazione Microsoft Entra che hai creato in precedenza.

7. Immetti il collegamento dell'endpoint fornito dal provider del sistema di monitoraggio esterno. Il collegamento dell'endpoint è lo stesso URL di base dell'endpoint che utilizzi quando configuri l'applicazione Microsoft Entra.

8. Nella sezione Imposta il comportamento in caso di errore, definisci il comportamento predefinito del sistema nel caso in cui il sistema di rilevamento delle minacce non risponda in tempo o risponda con un errore. Per impostazione predefinita, questa opzione è impostata su Consenti all'agente di rispondere, ma puoi anche scegliere l'opzione Blocca la query per ridurre ulteriormente il rischio.

   Nota

   Dopo la configurazione del rilevamento delle minacce, il sistema di rilevamento delle minacce viene attivato prima di qualsiasi chiamata dello strumento da parte di un agente. Se l'agente non riceve una decisione dal sistema (consentire o bloccare) entro un secondo, per impostazione predefinita procede a consentire l'esecuzione dello strumento come previsto. Per modificare il comportamento predefinito, configura Imposta comportamento in caso di errore.

9. Seleziona Salva.

Importante

Il salvataggio non riesce se la tua app Microsoft Entra non è configurata correttamente in Microsoft Entra o non è autorizzata correttamente con il provider selezionato.

Nota

Non esiste un'impostazione globale o a livello di tenant per abilitare automaticamente il provider di sicurezza esterno in tutti gli ambienti di Copilot Studio. Il rilevamento delle minacce esterne deve essere abilitato manualmente per ciascun ambiente tramite il portale di amministrazione di Copilot Studio. Ecco alcune considerazioni importanti:

• Il provider di sicurezza esterno viene configurato separatamente per ogni ambiente.
• Non esiste alcuna impostazione PowerShell, API o dell'interfaccia di amministrazione che consenta di applicare o propagare questa configurazione a livello globale per altri ambienti esistenti o futuri.
• Devi attivare il rilevamento delle minacce per ogni nuovo ambiente dopo aver creato l'ambiente.

Risoluzione dei problemi

Ecco alcune informazioni sui problemi che potrebbero verificarsi e su come gestirli.

Problemi di configurazione del rilevamento delle minacce dell'interfaccia di amministrazione di Power Platform

Nella tabella seguente vengono descritti gli errori comuni che possono verificarsi quando si seleziona Salva nel passaggio precedente e come gestire questi errori:

Errore	Come gestire
Si è verificato un problema durante il salvataggio delle impostazioni. Prova a salvare di nuovo e, se non funziona, contatta l'amministratore per assistenza.	Problema generale durante il salvataggio della configurazione. Riprova. In caso contrario, contatta Copilot Studio per ottenere supporto.
Si è verificato un problema durante la connessione al provider di protezione. Per assistenza, contatta il provider.	Questo errore viene visualizzato quando si verifica il timeout o l'esito negativo di una chiamata all'endpoint specificato. Contatta il provider e verifica che non siano presenti problemi con il servizio.
Si è verificato un problema durante la connessione al provider di protezione. Prova a controllare il collegamento all'endpoint. Se non funziona, contatta il fornitore della protezione per supporto.	Questo errore viene visualizzato quando si verifica il timeout di una chiamata all'endpoint specificato. Controlla il collegamento dell'endpoint fornito e, se non funziona, contatta il fornitore del servizio di rilevamento minacce e verifica che non ci siano problemi con il suo servizio.
Si è verificato un problema durante la connessione al provider di protezione. Prova a salvare di nuovo e, se non funziona, contatta il provider della protezione per assistenza.	Questo errore viene visualizzato quando si verifica il timeout di una chiamata all'endpoint specificato. Riprova e, se non funziona, contatta il fornitore e verifica che non ci siano problemi con il servizio.
Si è verificato un problema con la configurazione. Prova a controllare i dettagli inseriti e la configurazione di Microsoft Entra. Se il problema persiste, contatta l'amministratore per assistenza.	Acquisizione del token non riuscita. Controlla la configurazione dell'applicazione Microsoft Entra e le credenziali di identità federate. Altri dettagli sul problema specifico sono disponibili dopo aver selezionato "Copia informazioni sull'errore".
Per modificare una configurazione, assicurati di disporre delle autorizzazioni di amministratore di Power Platform.	Disporre di un utente con le autorizzazioni necessarie

Per ulteriori dettagli sull'errore, seleziona Copia informazioni sull'errore.

Problemi comuni relativi a Microsoft Entra e autenticazione

Ecco alcuni altri problemi comuni che possono verificarsi con l'app Microsoft Entra e l'autenticazione.

L'applicazione Microsoft Entra non esiste

Esempio: impossibile acquisire il token: AADSTS700016: l'applicazione con identificatore "00001111-aaaa-2222-bbbb-3333cccc4444" non è stata trovata nella directory "Contoso". Ciò può verificarsi se l'applicazione non è installata dall'amministratore del tenant o ha acconsentito a qualsiasi utente nel tenant. La richiesta di autenticazione potrebbe essere stata inviata al tenant sbagliato.

Come gestire: assicurati che l'ID applicazione fornito sia corretto ed esistente in Azure.

Nessun FIC configurato nell'app

Esempio: impossibile acquisire il token: un problema di configurazione impedisce l'autenticazione: verifica il messaggio di errore del server per i dettagli. Puoi modificare la configurazione nel portale di registrazione dell'applicazione. Vedi https://aka.ms/msal-net-invalid-client per i dettagli. Eccezione originale: AADSTS70025: il client "00001111-aaaa-2222-bbbb-3333cccc4444"(test Webhooks) non ha credenziali di identità federate configurate.

Come gestire: l'app fornita non ha alcuna FIC configurata. Segui la documentazione e configura FIC di conseguenza.

Autorità di certificazione FIC non valida

Esempio: impossibile acquisire il token: un problema di configurazione impedisce l'autenticazione: verifica il messaggio di errore del server per i dettagli. Puoi modificare la configurazione nel portale di registrazione dell'applicazione. Vedi https://aka.ms/msal-net-invalid-client per i dettagli. Eccezione originale: AADSTS7002111: nessun record di identità federato corrispondente trovato per l'emittente dell'asserzione presentato "https://login.microsoftonline.com/262d6d26-0e00-40b3-9c2f-31501d4dcbd1/v2.0". Assicurati che l'autorità di certificazione delle credenziali di identità federata sia "https://login.microsoftonline.com/{tenantId}/v2.0".

Come gestire: nessun FIC con l'autorità di certificazione prevista è stato trovato nell'app. Apri la configurazione del tuo FIC e imposta l'emittente su https://login.microsoftonline.com/{tenantId}/v2.0 (inserendo l'ID del tenant).

Oggetto FIC non valido

Esempio: impossibile acquisire il token: un problema di configurazione impedisce l'autenticazione: verifica il messaggio di errore del server per i dettagli. Puoi modificare la configurazione nel portale di registrazione dell'applicazione. Vedi https://aka.ms/msal-net-invalid-client per i dettagli. Eccezione originale: AADSTS7002137: nessun record di identità federato corrispondente trovato per il soggetto dell'asserzione presentato '/eid1/c/pub/t/Jm0tJgAOs0CcLzFQHU3L0Q/a/iDQPIrayM0GBBVzmyXgucw/aHR0cHM6Ly9jb250b3NvLnByb3ZpZGVyLmNvbeKAiw'. Assicurati che il soggetto delle credenziali dell'identità federata sia '/eid1/c/pub/t/{tenantId}/a/iDQPIrayM0GBBVzmyXgucw/aHR0cHM6Ly9jb250b3NvLnByb3ZpZGVyLmNvbeKAiw'.

Come gestire: nessun FIC con l'oggetto prevista è stato trovato nell'app. Apri la configurazione del FIC e imposta l'oggetto al valore atteso come suggerito nell'errore (inserisci il tuo ID tenant). Assicurati che non siano presenti spazi vuoti aggiuntivi o righe vuote nei campi oggetto.

L'app non è consentita con il provider (specifico di Microsoft Defender)

Esempio: l'ID applicazione nel token di autenticazione non corrisponde all'applicazione registrata per l'accesso webhook. Assicurati di usare le credenziali dell'applicazione corrette.

Come gestire: l'applicazione non è inclusa nella lista delle applicazioni autorizzate dal fornitore. Per concedere l'accesso al webhook dell'app, vedi la documentazione del provider.

Disconnetti la protezione dal sistema di rilevamento delle minacce

Se non desideri più che il sistema di rilevamento delle minacce monitori il tuo agente, segui questi passaggi:

1. Accedi all'interfaccia di amministrazione di Power Platform.

2. Seleziona Sicurezza nel riquadro di spostamento laterale, quindi Rilevamento delle minacce. Si apre la pagina Rilevamento delle minacce.

3. Seleziona Rilevamento minacce aggiuntivo. Verrà aperto un riquadro.

4. Seleziona l'ambiente per cui vuoi disattivare la protezione degli agenti avanzata e seleziona Configura. Verrà aperto un riquadro.

5. Deseleziona la casella di controllo Consenti a Copilot Studio di condividere i dati con il provider selezionato.

6. Seleziona Salva.