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 viene aggiunto automaticamente un argomento di sistema denominato log in. Per utilizzarlo, devi impostare l'autenticazione agente su manuale e richiedere agli utenti di effettuare l'accesso. Quando un cliente avvia una conversazione con agente, si attiva il log in argomento che chiede all'utente di effettuare l'accesso. Puoi personalizzare l' accesso argomento in base alle tue esigenze per il tuo agente.
Importante
È consigliabile che l'argomento Accesso venga utilizzato solo per fornire il metodo di autenticazione fornito da Copilot Studio. Non dovrebbe essere modificato per richiamare altre azioni o flussi, né altri metodi di autenticazione.
Apri agente in Copilot Studio, Seleziona Impostazioni nella parte superiore della pagina, quindi Seleziona 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 Autenticazione .
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.
Deseleziona 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 con l'esperienza di accesso del provider di identità.
Variabili di autenticazione
Quando configuri l'autenticazione utente per il tuo 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 Usare le 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à. Utilizza questa variabile per salutare o fare riferimento all'utente senza che debba fornire esplicitamente il suo nome all'agente, rendendo la conversazione più personalizzata.
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 dell'utente archiviato nel provider di identità. Usa questa variabile nei flussi Power Automate per chiamare le API che accettano l'ID utente come valore.
Copilot Studio imposta automaticamente il valore di 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. L'opzione Richiedi agli utenti di effettuare l'accesso deve essere attivata.
Initializer indica che quando un utente non ha effettuato l'accesso e raggiunge un puntare nella conversazione che utilizza variabili di autenticazione, gli viene chiesto di effettuare l'accesso.
Variabili di autenticazione
Se il tuo agente è configurato con le opzioni di autenticazione Autenticazione con Microsoft o Manuale , hai a disposizione un set di variabili di autenticazione nei tuoi argomenti. Per maggiori informazioni su come configurare l'autenticazione nel tuo agente, consulta 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 usare questa variabile per salutare o fare riferimento all'utente finale senza che debba comunicarlo esplicitamente a agente, 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. 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à. 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. Copilot Studio estrae automaticamente questo campo nella variabile.
Avviso
Non viene garantito che le variabili User.DisplayName e User.Id 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 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 al riquadro Test del bot ; non è possibile utilizzarli in un agente pubblicato e distribuito su un canale.
Inserisci il comando desiderato nel riquadro Test del bot proprio come faresti normalmente se stessi chattando con agente. Se l'operazione va a buon fine, riceverai un messaggio di conferma da agente. Se il tuo agente non utilizza l'autenticazione, riceverai un errore.
Se ripristini il riquadro Test del bot (o apporti modifiche a un argomento che fa sì che Test del bot si ripristini automaticamente), sarà 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 la tua opzione di autenticazione è impostata su Esegui autenticazione con Microsoft, non hai la possibilità di aggiungere esplicitamente l'autenticazione ai tuoi 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.
Una volta configurato agente SSO , all'utente non verrà richiesto di effettuare l'accesso.
Per aggiungere un nodo Autenticazione al tuo argomento:
Vai alla pagina Argomenti per l'agente che vuoi modificare.
Apri l'argomento a cui desideri aggiungere il modello di autenticazione.
Nota
Se il tuo agente è connesso a Dynamics 365 servizio clienti,, il nodo Autenticazione non può far parte del percorso di conversazione che agente segue quando saluta inizialmente gli utenti; in caso contrario, l'accesso scheda verrà mostrato 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 il testo che agente deve contenere 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 nel mezzo di un'interazione. 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 passi la variabile User.AccessToken senza che l'utente passi prima attraverso il nodo Autentica, all'utente verrà richiesto di accedere a quel 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 durante una conversazione, verrà richiesto di accedere nuovamente se l'argomento arriva a un nodo che utilizza la variabile User.AccessToken.
Percorso di successo
Il percorso di successo equivale a dove User.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 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, 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à.