Aggiungi l'autenticazione utente finale a un copilota

Importante

Le capacità e funzionalità di Power Virtual Agents ora fanno parte di Microsoft Copilot Studio a seguito di investimenti significativi nell'intelligenza artificiale generativa e integrazioni migliorate in Microsoft Copilot.

Alcuni articoli e schermate potrebbero fare riferimento a Power Virtual Agents durante l'aggiornamento della documentazione e dei contenuti per il training.

Puoi abilitare l'autenticazione utente direttamente all'interno di una conversazione del copilota. Autenticazione utente significa che puoi ottenere le proprietà di base di un utente come nome e ID nelle variabili, ma anche richiedere a un utente di accedere utilizzando un nodo di autenticazione, recuperare un token utente per quell'utente e quindi utilizzare quel token per recuperare le informazioni dell'utente da un sistema di back-end.

Nota

I copiloti creati nell'app Web e in Microsoft Teams vengono forniti con l'autenticazione preconfigurata per utilizzare l'autenticazione Solo per Teams e Power Apps.

Puoi anche configurare Single Sign-On (SSO) in modo che gli utenti non debbano accedere manualmente. Per ulteriori informazioni, vedi Configurare SSO per il Web.

Prerequisiti

• Usare le variabili
• Configurare autenticazione utente finale.

Applicazione Web

Aggiungi l'autenticazione utente a un argomento per consentire ai clienti di accedere direttamente alla conversazione. Puoi quindi personalizzare la conversazione con variabili utente e accedere ai sistemi di back-end per conto dell'utente.

Configurare l'autenticazione manuale con Microsoft Entra ID

È necessario configurare l'autenticazione utente con Microsoft Entra ID prima di poter utilizzare l'autenticazione nei tuoi argomenti.

1. Segui le istruzioni in Configurare l'autenticazione utente con Microsoft Entra ID.
2. Torna a questo articolo.

Aggiungere l'autenticazione utente con l'argomento del sistema di accesso

Quando crei un copilota, Microsoft Copilot Studio aggiunge automaticamente un sistema argomento chiamato Accedi. Per utilizzarlo, devi impostare l'autenticazione del tuo copilota su manuale e richiedere agli utenti di accedere. Quando un cliente avvia una conversazione con il copilota, l'argomento Accedi si attiva e richiede all'utente di accedere. Puoi personalizzare l'argomento Accedi in modo appropriato per il tuo copilota.

1. Nel menu di navigazione, in Impostazioni seleziona Sicurezza.

2. Seleziona il riquadro Autenticazione.

3. Seleziona Manuale (per sito web personalizzato), quindi seleziona Richiedi agli utenti di accedere.

   

   

Aggiungere l'autenticazione utente con un argomento personalizzato

L'argomento Accesso autentica l'utente all'inizio della conversazione. Per consentire all'utente di accedere in un secondo momento, puoi aggiungere un nodo Autentica a qualsiasi argomento personalizzato.

Quando i clienti immettono nome utente e password, potrebbe essere richiesto di immettere un codice di convalida. Dopo l'accesso, non verrà più richiesto, anche se raggiungono un altro nodo Autentica.

1. Nel menu di navigazione, in Impostazioni seleziona Sicurezza.

2. Seleziona il riquadro Autenticazione.

3. Disattiva Richiedi agli utenti di accedere.

4. Nel menu di spostamento, seleziona Argomenti e quindi apri l'argomento a cui vuoi aggiungere l'autenticazione.

5. Seleziona Aggiungi nodo (+), seleziona Chiama un'azione, quindi seleziona Autenticazione.

6. Testa il tuo argomento con un utente configurato nel tuo provider di identità.

Suggerimento

È importante creare percorsi per l'accesso riuscito e non riuscito. Un accesso potrebbe non riuscire per molti motivi, inclusi errori con l'esperienza di accesso del provider di identità.

Variabili di autenticazione

Dopo aver configurato l'autenticazione utente per il tuo copilota, puoi utilizzare le variabili di autenticazione nei tuoi argomenti. La tabella seguente confronta la disponibilità delle variabili in base all'opzione di autenticazione scelta.

Variabile di autenticazione	Nessuna autenticazione	Solo per Teams e Power Apps	Manuale
User.DisplayName	non disponibile	disponibile	disponibile
User.FirstName	non disponibile	disponibile	disponibile
User.LastName	non disponibile	disponibile	disponibile
User.PrincipalName	non disponibile	disponibile	disponibile
User.Email	non disponibile	disponibile	disponibile
User.Id	non disponibile	disponibile	disponibile
User.IsLoggedIn	non disponibile	disponibile	disponibile
User.AccessToken	non disponibile	non disponibile	disponibile
SignInReason	non disponibile	disponibile	disponibile

User.DisplayName

Avviso

Non è garantito che questa variabile contenga un valore. Prova con un utente del tuo provider di identità per assicurarti che i tuoi argomenti funzionino correttamente.

La variabile User.DisplayName contiene il nome visualizzato archiviato nel provider di identità. Usa questa variabile per salutare o fare riferimento all'utente finale senza che questi debba dare il proprio nome al copilota, rendendo la conversazione più personalizzata.

Microsoft Copilot Studio imposta automaticamente il valore di User.DisplayName dall'attestazione name fornita dal provider di identità, purché l'ambito profile sia stato definito quando è stata configurata l'autenticazione manuale. Per ulteriori informazioni sull'ambito, vedi Configurare l'autenticazione utente con Microsoft Entra ID.

User.Id

Avviso

Non è garantito che questa variabile contenga un valore. Prova con un utente del tuo provider di identità per assicurarti che i tuoi argomenti funzionino correttamente.

La variabile User.Id contiene l'ID utente archiviato nel provider di identità. Usa questa variabile nei flussi Power Automate per chiamare le API che accettano l'ID utente come valore.

Microsoft Copilot Studio imposta automaticamente il valore di User.DisplayName dall'attestazione sub fornita dal provider di identità.

User.IsLoggedIn

User.IsLoggedIn è una variabile di tipo booleano che archivia lo stato di accesso dell'utente. Un valore di true indica che l'utente ha effettuato l'accesso. Puoi utilizzare questa variabile per creare una logica di diramazione nei propri argomenti che verifica la corretta riuscita dell'accesso o per recuperare le informazioni sull'utente solo se l'utente ha effettuato l'accesso.

User.AccessToken

Avviso

Assicurati di passare la variabile User.AccessToken solo a fonti attendibili. Contiene informazioni sull'autenticazione dell'utente, che, se compromesse, potrebbero danneggiare l'utente.

La variabile User.AccessToken contiene il token dell'utente, ottenuto dopo l'accesso dell'utente. Puoi passare questa variabile ai flussi Power Automate in modo che possano connettersi alle API back-end e recuperare le informazioni dell'utente o intraprendere azioni per conto dell'utente.

Non utilizzare User.AccessToken nei nodi Messaggio o nei flussi di cui non ti fidi.

SignInReason

SignInReason è una variabile di tipo scelta che indica quando l'utente deve effettuare l'accesso. Ha due valori possibili:

• SignInRequired indica che l'utente deve effettuare l'accesso all'inizio della conversazione utilizzando l'argomento di sistema Accesso. Richiedi agli utenti di accedere deve essere attivata.

• Initializer indica che se l'utente non ha ancora effettuato l'accesso e raggiunge un punto della conversazione che utilizza variabili di autenticazione, gli verrà chiesto di accedere.

Classico

Variabili di autenticazione

Se il tuo bot è configurato con le opzioni di autenticazione Solo per Teams e Power Apps o Manuale, avrai a disposizione una serie di variabili di autenticazione nei tuoi argomenti. Vedi la documentazione di configurazione dell'autenticazione per ulteriori informazioni su come configurare l'autenticazione nel tuo bot.

La tabella seguente confronta la disponibilità delle variabili di autenticazione in base all'opzione di configurazione dell'autenticazione:

Variabile di autenticazione	Nessuna autenticazione	Solo per Teams e Power Apps	Manuale
UserDisplayName	❌	✔️	✔️
UserID	❌	✔️	✔️
IsLoggedIn	❌	❌	✔️
AuthToken	❌	❌	✔️

Variabile UserDisplayName

La variabile UserDisplayName contiene il nome visualizzato dell'utente archiviato nel provider di identità. Puoi utilizzare questa variabile per salutare o fare riferimento all'utente finale senza che questi debba comunicarlo esplicitamente al bot, rendendolo più personalizzato.

Questo valore di campo è ottenuto da un'attestazione Microsoft Entra ID name. Per i provider OAuth, questo è il valore archiviato nell'attestazione name. Microsoft Copilot Studio estrae automaticamente questo campo nella variabile, quindi assicurati di avere profile come parte della configurazione dell'ambito di autenticazione.

Variabile UserID

La variabile UserID contiene l'ID dell'utente archiviato nel provider di identità. Questo valore può essere utilizzato dai flussi di Power Automate per chiamare API che accettano l'ID utente come valore. Questo valore di campo è ottenuto da un'attestazione Microsoft Entra ID sub. Per i provider OAuth, questo è il valore archiviato nell'attestazione sub. Microsoft Copilot Studio estrae automaticamente questo campo nella variabile.

Avviso

Non viene garantito che le variabili UserDisplayName e UserID siano compilate e potrebbero essere stringhe vuote a seconda della configurazione dell'utente nel provider di identità. Prova con un utente del tuo provider di identificazione per assicurarti che i tuoi argomenti funzionino correttamente, anche se queste variabili sono vuote.

Variabile IsLoggedIn

La variabile IsLoggedIn indica se l'utente ha effettuato l'accesso (come risultato dell'accesso o se è già connesso, noto anche come percorso di accesso completato) o non ha effettuato l'accesso (che sarebbe il percorso di errore di accesso).

IsLoggedIn è una variabile di tipo booleano che contiene lo stato di accesso dell'utente. Puoi utilizzare questa variabile per creare una logica di diramazione nei propri argomenti che verifica la corretta riuscita dell'accesso (ad esempio, nel modello già fornito come parte dell'aggiunta del nodo Autentica) o per recuperare opportunisticamente le informazioni sull'utente solo se l'utente ha effettuato l'accesso.

Variabile AuthToken

La variabile AuthToken contiene il token dell'utente, ottenuto dopo l'accesso dell'utente. Puoi passare questa variabile ai flussi Power Automate in modo che possano connettersi alle API back-end e recuperare le informazioni dell'utente o intraprendere azioni per conto dell'utente.

Avviso

Assicurati di passare la variabile AuthToken solo a fonti attendibili. Contiene informazioni sull'autenticazione dell'utente, che, se compromesse, potrebbero danneggiare l'utente.

Non utilizzare AuthToken dentro i nodi Messaggio o su flussi di cui non ti fidi.

Verifica delle variabili di autenticazione

Per impostazione predefinita, il riquadro Bot di prova utilizzerà l'account dell'utente attualmente connesso per popolare le variabili UserDisplayName e UserID. Tuttavia, durante il test di argomenti che utilizzano l'autenticazione, potresti voler utilizzare altri valori per queste variabili (o anche un valore vuoto).

Ad esempio, potresti voler testare come vengono utilizzati i caratteri speciali o cosa succede se la variabile è vuota.

Questo vale solo per il riquadro Bot di prova; non è possibile utilizzare i comandi descritti in questa sezione in un bot pubblicato distribuito su un canale.

La tabella seguente elenca i comandi che popoleranno queste variabili. Immettere il comando nel riquadro Bot di prova proprio come faresti se stessi chattando normalmente con il bot. Riceverai un messaggio di conferma dal bot se hai successo. Se il tuo bot non utilizza l'autenticazione, riceverai un errore.

Se ripristini il riquadro Bot di prova (o apporti modifiche a un argomento che fa sì che il Bot di prova si ripristini automaticamente), sarà necessario inviare nuovamente i comandi.

Variabile	Comando Valore personalizzato	Comando valore vuoto (vuoto)
UserDisplayName	/debug set bot.UserDisplayName "Value"	/debug set bot.UserDisplayName ""
UserID	Non disponibile	/debug set bot.UserID ""

Importante

Non puoi popolare la variabile UserID con un valore personalizzato (diverso da un valore vuoto) per motivi di sicurezza.

Autenticazione quando si utilizza la configurazione "Solo per teams e Power Apps"

Se la tua opzione di autenticazione è impostata su Solo per Teams e Power Apps, non è necessario aggiungere esplicitamente l'autenticazione ai tuoi argomenti. In questa configurazione, qualsiasi utente in Microsoft Teams esegue automaticamente l'accesso tramite le credenziali di Teams e non è necessario accedere esplicitamente con una scheda di autenticazione. Se la tua opzione di autenticazione è impostata su Manuale, dovrai aggiungere il nodo di autenticazione (anche per il canale Teams).

Nota

Se la tua opzione di autenticazione è impostata su Solo per Teams e Power Apps, non hai la possibilità di aggiungere esplicitamente l'autenticazione ai tuoi argomenti.

Aggiungi l'autenticazione utente a un argomento

Il nodo Autenticazione chiederà a un utente di accedere con una scheda di accesso. Se un utente ha già effettuato l'accesso, non verrà più richiesto, anche se raggiunge un altro nodo Autenticazione.

Una volta che l'utente inserisce nome utente e password nel prompt (ospitato dal provider di identità), potrebbe essere richiesto di immettere un codice di convalida, a seconda del canale. Alcuni canali, ad esempio Microsoft Teams, non richiedono all'utente di inserire un codice di convalida.

Quando il tuo bot ha SSO configurato, all'utente non verrà richiesto di effettuare l'accesso.

Per aggiungere un nodo autenticazione al tuo argomento:

1. Vai alla Pagina Argomenti per il bot che desideri modificare.

2. Apri l'area del contenuto per l'argomento a cui desideri aggiungere il modello di autenticazione.

   Nota

   Se il tuo bot è connesso a Dynamics 365 Customer Service, il nodo Autenticazione non può far parte del percorso di conversazione seguito dal bot quando saluta inizialmente gli utenti, altrimenti la scheda di accesso verrà mostrata due volte. Dovresti aggiungere il nodo Autenticazione a un altro argomento che viene attivato da una risposta dell'utente.

3. Seleziona Aggiungi nodo (+) per aggiungere un nodo messaggio. Inserisci cosa dovrebbe dire il bot per indicare che sta per verificarsi un'esperienza di accesso.

   

4. Sotto il nodo del messaggio, seleziona Aggiungi nodo (+), seleziona Chiama un'azione e quindi seleziona Autentica.

   

   Nota

   Il nodo Autentica è disponibile solo nella selezione delle azioni alla fine dell'albero di interazione (come nodo foglia). Non può essere aggiunto nel mezzo di un'interazione. Una volta aggiunto, altri nodi possono essere aggiunti al di sotto di esso.

5. Una volta selezionato, un numero di nuovi nodi verrà aggiunto automaticamente. Questi nodi includono un nodo Autentica padre, seguito da nodi sia per un percorso di successo che per un percorso di errore.

   

Utilizzo AuthToken senza un nodo Autentica

Le variabili IsLoggedIn e AuthToken sono disponibili anche se non si utilizza il modello fornito dalla voce di menu Chiama un'azione. Se passi la variabile AuthToken senza che l'utente passi prima attraverso il nodo Autentica, all'utente verrà richiesto di accedere a quel passaggio.

Passando la variabile AuthToken può essere utile se ti aspetti sempre che l'utente acceda o se il tuo utente viene reindirizzato da un diverso argomento. Ti consigliamo di utilizzare il modello fornito dalla voce Chiama un'azione per trattare i casi in cui l'utente non riesce ad accedere.

Nota

Se l'utente si disconnette durante una conversazione, verrà richiesto di accedere nuovamente se l'argomento arriva a un nodo che utilizza la variabile AuthToken.

Percorso di successo

Il percorso di successo equivale a dove IsLoggedIn = True e gli account per quando l'utente ha effettuato correttamente l'accesso (o aveva già effettuato l'accesso).

Se disponi di una logica che utilizza la variabile AuthToken (ad esempio, per connettersi a un sistema back-end utilizzando un flusso per recuperare le informazioni di un utente), dovrebbe andare in questo percorso.

Percorso di errore

Il percorso di errore equivale a qualsiasi condizione diversa da IsLoggedIn = True. Nella maggior parte dei casi il percorso di errore si verifica perché l'utente non è riuscito ad accedere, ha utilizzato la password errata o ha annullato l'esperienza di accesso.

Aggiungi qualsiasi logica che potresti voler trattare in questo caso. Ad esempio, abbiamo fornito opzioni per riprovare o per scalare a un agente live. Personalizza le azioni del percorso di errore per il tuo particolare scenario e utilizzo.

Test del tuo argomento

Assicurati di testare il tuo argomento utilizzando un utente reale configurato nel tuo provider di identità. Assicurati che vengano eseguiti i percorsi di successo e di errore di accesso, così da non avere sorprese se l'utente non riesce ad accedere o si verifica un errore con l'esperienza di accesso del provider di identità.

Argomenti correlati

Puoi anche configurare Single Sign-On (SSO) in modo che gli utenti non debbano accedere manualmente. Per ulteriori informazioni, vedi Configurare SSO per il Web.