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 copilota, 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.
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 il copilota in Copilot Studio, seleziona Impostazioni nella parte superiore della pagina, quindi seleziona Sicurezza.
Seleziona il riquadro 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 l'accesso, non verrà più richiesto, anche se raggiungono un altro nodo 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.
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
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.
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.
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.
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.
Variabili di autenticazione
Se il tuo copilota è 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. Per ulteriori informazioni su come configurare l'autenticazione nel tuo copilota, 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 |
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 copilota, 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 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. 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 copilota pubblicato distribuito su un canale.
La tabella seguente elenca i comandi che popoleranno queste variabili. Immetti il comando nel riquadro Bot di prova proprio come faresti se stessi chattando normalmente con il copilota. Riceverai un messaggio di conferma dal copilota se hai successo. Se il tuo copilota 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 copilota ha SSO configurato, all'utente non verrà richiesto di effettuare l'accesso.
Per aggiungere un nodo autenticazione al tuo argomento:
Vai alla pagina Argomenti per il copilota che desideri modificare.
Apri l'area del contenuto per l'argomento a cui desideri aggiungere il modello di autenticazione.
Nota
Se il copilota è connesso a Dynamics 365 Customer Service, il nodo Autenticazione non può far parte del percorso di conversazione seguito dal copilota quando saluta inizialmente gli utenti; in caso contrario, 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.
Seleziona Aggiungi nodo (+) per aggiungere un nodo messaggio. Inserisci cosa dovrebbe dire il copilota 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.
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à.