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.
È necessario configurare l'autenticazione utente con Microsoft Entra ID prima di poter utilizzare l'autenticazione nei tuoi argomenti.
Segui le istruzioni in Configurare l'autenticazione utente con Microsoft Entra ID.
Aggiungere l'autenticazione utente con l'argomento di sistema Accedi
Quando crei un agente, Copilot Studio aggiunge automaticamente un argomento di sistema chiamato Accedi. Per utilizzarlo, devi impostare l'autenticazione del tuo agente su manuale e richiedere agli utenti di accedere. Quando un cliente avvia una conversazione con agente, si attiva l'argomento di accesso e chiede all'utente di accedere. Puoi personalizzare l'argomento Accedi in modo appropriato per l'agente.
Importante
Ti consigliamo di utilizzare l'argomento Accedi solo per offrire il metodo di autenticazione fornito da Copilot Studio. Non dovrebbe essere modificato per richiamare altre azioni o flussi, né altri metodi di autenticazione.
- Apri l'agente in Copilot Studio e seleziona Impostazioni nella parte superiore della pagina e poi Sicurezza.
- Seleziona Autenticazione.
- Seleziona Autentica manualmente, quindi seleziona Richiedi agli utenti di accedere.
-
Configura tutti i campi di autenticazione manuale, come richiesto.
- Seleziona Salva.
Aggiungere l'autenticazione utente con un argomento personalizzato
L'argomento Accedi 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 inseriscono nome utente e password, potrebbe essere loro richiesto di inserire un codice di convalida. Dopo aver effettuato l'accesso, non verrà loro chiesto di nuovo di effettuare l'accesso, anche se raggiungono un altro nodo di Autentica.
Nella parte superiore della pagina, seleziona Impostazioni, quindi seleziona Sicurezza.
Seleziona il riquadro Autenticazione.
Nota
Devi selezionare Autentica manualmente per aggiungere l'autenticazione utente a un argomento personalizzato.
Selezionare Autentica manualmente e deselezionare la casella di controllo Richiedi agli utenti di accedere .
Configura tutti i campi di autenticazione manuale, come richiesto.
Seleziona Salva.
Seleziona Argomenti nella parte superiore della pagina.
Seleziona Aggiungi nodo ( 
) >Avanzate>Esegui autenticazione.
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 relativi all'esperienza di accesso del provider di identità.
Variabili di autenticazione
Quando configuri l'autenticazione utente per l'agente, puoi utilizzare variabili di autenticazione nei tuoi argomenti. La tabella seguente confronta la disponibilità delle variabili in base all'opzione di autenticazione scelta.
Per ulteriori informazioni sulle variabili, vedi Panoramica delle variabili.
| Variabile di autenticazione |
Nessuna autenticazione |
Esegui l'autenticazione con Microsoft |
Esegui l'autenticazione manuale |
|
User.DisplayName |
Non disponibile |
Disponibili |
Disponibili |
| User.FirstName |
Non disponibile |
Disponibili |
Disponibili |
| User.LastName |
Non disponibile |
Disponibili |
Disponibili |
| User.PrincipalName |
Non disponibile |
Disponibili |
Disponibili |
| User.Email |
Non disponibile |
Disponibili |
Disponibili |
|
User.Id |
Non disponibile |
Disponibili |
Disponibili |
|
User.IsLoggedIn |
Non disponibile |
Disponibili |
Disponibili |
|
User.AccessToken |
Non disponibile |
Non disponibile |
Disponibili |
|
SignInReason |
Non disponibile |
Disponibili |
Disponibili |
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 all'agente, rendendo la conversazione più personalizzata.
Copilot Studio imposta automaticamente il valore 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 dell'utente archiviato nel provider di identità. Usa questa variabile nei flussi Power Automate per chiamare le API che accettano UserID come valore.
Copilot Studio imposta automaticamente il valore User.DisplayName dall'attestazione sub fornita dal provider di identità.
User.IsLoggedIn
User.IsLoggedIn è una variabile booleana che memorizza 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 quando un utente non ha effettuato l'accesso e raggiunge un punto della conversazione che utilizza variabili di autenticazione, gli viene chiesto di effettuare l'accesso.
Variabili di autenticazione
Se l'agente è configurato con le opzioni di autenticazione Esegui autenticazione con Microsoft o Manuale, avrai a disposizione una serie di variabili di autenticazione nei tuoi argomenti. Per ulteriori informazioni su come configurare l'autenticazione nell'agente, vedi Configurare l'autenticazione utente in Copilot Studio.
La tabella seguente confronta la disponibilità delle variabili di autenticazione in base all'opzione di configurazione dell'autenticazione:
| Variabile di autenticazione |
Nessuna autenticazione |
Esegui l'autenticazione con Microsoft |
Manuale |
User.DisplayName |
❌ |
✔️ |
✔️ |
User.Id |
❌ |
✔️ |
✔️ |
User.IsLoggedIn |
❌ |
❌ |
✔️ |
User.AccessToken |
❌ |
❌ |
✔️ |
Variabile UserDisplayName
La variabile User.DisplayName contiene il nome visualizzato dell'utente archiviato nel provider di identità. Puoi utilizzare questa variabile per salutare o fare riferimento al cliente senza che questi debba comunicarlo esplicitamente all'agente, rendendolo più personalizzato.
Questo valore di campo è ottenuto da un'attestazione Microsoft Entra ID name. Per i provider OAuth, questo valore è archiviato nell'attestazione name. 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 User.Id contiene l'ID dell'utente archiviato nel provider di identità. I flussi Power Automate possono utilizzare questo valore per chiamare le API che accettano UserID come valore.
Questo valore di campo è ottenuto da un'attestazione Microsoft Entra ID sub. Per i provider OAuth, questo valore è archiviato nell'attestazione sub. Copilot Studio estrae automaticamente questo campo nella variabile.
Avviso
Le User.DisplayName variabili e User.Id potrebbero non essere riempite e queste variabili potrebbero invece essere stringhe vuote a seconda della configurazione 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 User.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).
User.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 User.AccessToken
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.
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.
Non utilizzare User.AccessToken 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 User.DisplayName e User.Id. 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.
La tabella seguente elenca i comandi che popoleranno queste variabili. Questi comandi si applicano solo per il riquadro Test del bot; non è possibile utilizzarli in un agente distribuito su un canale.
Immettere il comando desiderato nel riquadro Bot di prova proprio come faresti se stessi chattando normalmente con l'agente. Se hai successo, riceverai un messaggio di conferma dall'agente. Se l'agente non usa l'autenticazione, viene visualizzato un errore.
Se si reimposta il riquadro Test bot (o si apportano modifiche a un argomento che causa la reimpostazione automatica del bot di test ), è necessario inviare nuovamente i comandi.
| Variabile |
Comando Valore personalizzato |
Comando valore vuoto (vuoto) |
User.DisplayName |
/debug set bot.UserDisplayName "Value" |
/debug set bot.UserDisplayName "" |
User.Id |
Non disponibile |
/debug set bot.UserID "" |
Importante
Non puoi popolare la variabile User.Id con un valore personalizzato (diverso da un valore vuoto) per motivi di sicurezza.
Autenticazione quando si utilizza "Autenticazione con Microsoft"
Se la tua opzione di autenticazione è impostata su Esegui autenticazione con Microsoft, 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 un nodo di autenticazione (anche per il canale Teams).
Nota
Se l'opzione di autenticazione è impostata su Autentica con Microsoft, non è possibile aggiungere in modo esplicito l'autenticazione agli argomenti.
Aggiungi l'autenticazione utente a un argomento
Il nodo Autentica richiede all'utente di accedere con una scheda di accesso. Una volta effettuato l'accesso, l'utente non riceve ulteriori richieste, 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 l'agente ha configurato SSO, all'utente non viene chiesto di effettuare l'accesso.
Per aggiungere un nodo Autenticazione al tuo argomento:
Vai alla pagina Argomenti per l'agente che desideri modificare.
Apri l'argomento a cui desideri aggiungere il modello di autenticazione.
Nota
Se l'agente è connesso a Dynamics 365 Customer Service, il nodo Autenticazione non può far parte del percorso di conversazione che l'agente segue al momento del saluto iniziale degli utenti; in caso contrario, la scheda di accesso viene visualizzata due volte. Dovresti aggiungere il nodo Autenticazione a un altro argomento che viene attivato da una risposta dell'utente.
Seleziona Aggiungi nodo (+) per aggiungere un nodo messaggio. Inserisci cosa dovrebbe dire l'agente per indicare che sta per verificarsi un'esperienza di accesso.
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 al centro di un dialogo. Una volta aggiunto, altri nodi possono essere aggiunti al di sotto di esso.
I nuovi nodi vengono visualizzati automaticamente: un nodo Autentica padre, seguito da nodi sia per un percorso di successo che per un percorso di errore.
Utilizzo di User.AccessToken senza un nodo Autentica
Le variabili User.IsLoggedIn e User.AccessToken sono disponibili anche se non si utilizza il modello fornito dalla voce di menu Chiama un'azione. Se si passa la User.AccessToken variabile senza prima che l'utente passi attraverso il nodo Autentica , all'utente viene richiesto di eseguire l'accesso in tale passaggio.
Passando la variabile User.AccessToken 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 al centro di una conversazione, viene richiesto di accedere di nuovo se l'argomento arriva a un nodo che usa la User.AccessToken variabile.
Percorso di successo
Il percorso di successo coincide con User.IsLoggedIn = True e tiene conto di quando l'utente ha effettuato l'accesso con successo.
Se disponi di una logica che utilizza la variabile User.AccessToken (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, sono disponibili opzioni per riprovare o passare a un agente umano. 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 di testare sia i percorsi di accesso riuscito che quelli di errore. In questo modo, non ci sono sorprese se l'utente non riesce ad accedere o si verifica un errore con l'esperienza di accesso del provider di identità.