Configurare Single Sign-On in con Microsoft Entra ID

Copilot Studio supporta Single Sign-On (SSO). SSO consente ai copiloti nel sito Web di far accedere i clienti se sono già connessi alla pagina o all'app in cui è distribuito il copilota.

Ad esempio, il copilota è ospitato sull'intranet aziendale o in un'app a cui l'utente ha già effettuato l'accesso.

Sono disponibili quattro passaggi principali per la configurazione di SSO per Copilot Studio:

1. Crea una registrazione app in Microsoft Entra ID per il canvas personalizzato.

2. Definire un ambito personalizzato per il tuo copilota.

3. Configura l'autenticazione in Copilot Studio per abilitare SSO.

4. Configura il codice HTML canvas personalizzato per abilitare SSO.

Prerequisiti

• Abilita l'autenticazione per l'utente finale con Microsoft Entra ID
• Aggiungi un argomento di autenticazione al tuo copilota
• Usare un canvas personalizzato

Nota

Per configurare SSO utilizzando altri provider OAuth 2.0, vedi Configurare Single Sign-On con provider OAuth generici.

Canali supportati

La tabella seguente descrive in dettaglio i canali che attualmente supportano SSO. Puoi suggerire il supporto per canali extra al forum delle idee di Microsoft Copilot Studio.

Canale	Supportato
Canali del servizio Azure Bot	Non supportato
Sito Web personalizzato	Supportato
Sito Web demo	Non supportato
Facebook	Non supportato
Microsoft Teams1	Supportato
App per dispositivi mobili	Non supportato
Multicanale per Customer Service2	Supportato

¹ Se hai anche il canale Teams abilitato, devi seguire le istruzioni di configurazione nella documentazione Configurare Single Sign-On con Microsoft Entra ID per i copiloti in Microsoft Teams. Se non si configurano le impostazioni SSO di Teams come indicato in quella pagina, gli utenti non riusciranno mai a eseguire l'autenticazione quando usano il canale Teams.

² È supportato solo il canale della live chat. Per ulteriori informazioni, vedi Configurare il passaggio a Dynamics 365 Customer Service.

Importante

SSO attualmente non è supportato quando un copilota viene:

• Pubblicato su un portale Power Apps.
• Pubblicato su un sito Web SharePoint come iframe.

Tuttavia, SSO è supportato per un copilota che è stato pubblicato su un sito Web SharePoint come componente SPFx.

Applicazione Web

Creare registrazioni app per il sito Web personalizzato

Per abilitare SSO, avrai bisogno di creare due registrazioni di app separate:

• Una registrazione dell'app di autenticazione, che consente l'autenticazione utente Microsoft Entra ID per il tuo copilota
• Una registrazione dell'app canvas che abilita SSO per la tua pagina web personalizzata

Per motivi di sicurezza, non consigliamo di riutilizzare la stessa registrazione dell'app sia per il copilota che per il sito Web personalizzato.

1. Segui le istruzioni in Configurare l'autenticazione dell'utente con Microsoft Entra ID per creare una registrazione dell'app di autenticazione.

2. Segui le istruzioni per creare la registrazione di un'app di autenticazione e per creare una seconda registrazione di app che serve come registrazione della tua app canvas.

3. Aggiungi l'ID della registrazione dell'app canvas alla registrazione dell'app di autenticazione.

Aggiungere un URL di scambio di token

Per aggiornare le impostazioni di autenticazione di Microsoft Entra ID in Copilot Studio, devi aggiungere l'URL di scambio del token per consentire alla tua app e a Copilot Studio di condividere informazioni.

1. Nel portale di Azure sul pannello di registrazione dell'app di autenticazione, vai a Esponi un'API.

2. In Ambiti, seleziona l'icona Copia negli appunti .

3. In Copilot Studio, nel menu di spostamento in Impostazioni, seleziona Sicurezza, quindi seleziona il riquadro Autenticazione.

4. Per URL di scambio token (richiesto per SSO), incolla l'ambito che hai copiato in precedenza.

5. Seleziona Salva.

Configurare la registrazione dell'app canvas

1. Dopo aver creato la registrazione dell'app canvas, vai a Autenticazione e seleziona Aggiungi una piattaforma.

2. In Configurazioni della piattaforma seleziona Aggiungi una piattaforma, quindi seleziona Web.

3. In URI di indirizzamento, inserisci l'URL della tua pagina web, ad esempio http://contoso.com/index.html.

   

4. Nella sezione Concessione implicita e flussi ibridi, attiva Token di accesso (usati per flussi impliciti) e Token ID (usati per i flussi impliciti ed ibridi).

5. Seleziona Configura.

Trova l'URL endpoint del token del tuo copilota

1. In Copilot Studio, apri il copilota, quindi seleziona Canali.

2. Seleziona App per dispositivi mobili.

3. In Endpoint token, seleziona Copia.

   

Configurare SSO nella pagina web

Utilizza il codice fornito nel repository GitHub di Copilot Studio per creare una pagina Web per l'URL di reindirizzamento. Copia il codice dal repository GitHub e modificalo seguendo le istruzioni seguenti.

Nota

Il codice nel repository GitHub richiede che l'utente selezioni un pulsante di accesso o acceda da un sito diverso. Per abilitare l'accesso automatico, aggiungi il seguente codice all'inizio di aysnc function main():

    (async function main() {
        if (clientApplication.getAccount() == null) {
           await clientApplication.loginPopup(requestObj).then(onSignin).catch(function (error) {console.log(error) });
        }
        // Add your BOT ID below 
        var theURL =

1. Vai alla pagina Panoramica nel portale di Azure e copia ID applicazione (client) e ID directory (tenant) dalla registrazione dell'app canvas.

   

2. Per configurare la libreria di autenticazione Microsoft (MSAL):

   • Assegna clientId al tuo ID applicazione (client).
   • Assegna authority a https://login.microsoftonline.com/ e aggiungi il tuo ID directory (tenant) alla fine.

   Ad esempio:

   var clientApplication;
       (function (){
       var msalConfig = {
           auth: {
               clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
               authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'     
           },
   

3. Imposta la variabile theURL sull'URL del token endpoint che hai copiato in precedenza. Ad esempio:

   (async function main() {
   
       var theURL = "https://<token endpoint URL>"
   

4. Modifica il valore di userId per includere un prefisso personalizzato. Ad esempio:

   var userId = clientApplication.account?.accountIdentifier != null ? 
           ("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64) 
           : (Math.random().toString() + Date.now().toString()).substr(0,64);
   

5. Salva le modifiche.

Metti alla prova il tuo copilota utilizzando la tua pagina Web

1. Apri la tua pagina web nel browser.

2. Selezionare Accedi.

   

   Nota

   Se il tuo browser blocca i popup o stai utilizzando una finestra di navigazione in incognito o privata, ti verrà richiesto di accedere. Altrimenti, l'accesso viene completato utilizzando un codice di convalida.

   Si apre una nuova scheda del browser.

3. Passa alla nuova scheda e copia il codice di convalida.

4. Torna alla scheda con il tuo copilota e incolla il codice di convalida nella conversazione del copilota.

Contenuto correlato

• Registrazione dell'app di Azure

Classico

Panoramica tecnica

La seguente illustrazione mostra come un utente ha effettuato l'accesso senza vedere un prompt di accesso (SSO) in Copilot Studio:

1. L'utente del copilota inserisce una frase che attiva un argomento di accesso. L'argomento accesso è progettato per far accedere l'utente e utilizzare il token autenticato (variabile User.AccessToken) dell'utente.

2. Copilot Studio invia una richiesta di accesso per consentire all'utente di accedere con il proprio provider di identità configurato.

3. Il canvas personalizzato del copilota intercetta la richiesta di accesso e richiede un token On-Behalf-Of (OBO) di Microsoft Entra ID. Il canvas invia il token al copilota.

4. Alla ricezione del token OBO, il copilota scambia il token OBO con un "token di accesso" e compila la variabile AuthToken utilizzando il valore del token di accesso. Anche la variabile IsLoggedIn è impostata in questo momento.

Crea una registrazione app in Microsoft Entra ID per il canvas personalizzato

Per abilitare SSO, sono necessarie due registrazioni di app separate:

• Una per il tuo copilota per abilitare l'autenticazione utente con Microsoft Entra ID.
• Una per il canvas personalizzato per abilitare SSO.

Importante

Non puoi riutilizzare la stessa registrazione dell'app sia per l'autenticazione utente del tuo copilota e per il canvas personalizzato.

Creare una registrazione di app per il canvas del copilota

1. Accedi al portale di Azure.

2. Vai a Registrazioni di app, selezionando l'icona o cercando nella barra di ricerca in alto.

   

3. Seleziona Nuova registrazione.

   

4. Immetti un nome per la registrazione. Può essere utile utilizzare il nome del copilota di cui stai registrando il canvas e includere "canvas" per separarlo dalla registrazione dell'app per l'autenticazione.

   Ad esempio, se il tuo copilota si chiama "Contoso sales help", potresti denominare la registrazione dell'app come "ContosoSalesCanvas" o qualcosa di simile.

5. In Tipi di account supportati, seleziona Account in qualsiasi tenant organizzativo (qualsiasi directory di Microsoft Entra ID - Multitenant) e account Microsoft personali (ad esempio Skype, Xbox).

6. Lascia la sezione URI di reindirizzamento vuota per il momento, poiché inserirai le informazioni nei passaggi successivi. Selezionare Registrazione.

   

7. Una volta completata la registrazione, viene aperta la pagina Panoramica. Vai a Manifesto. Verifica che accessTokenAcceptedVersion sia impostato su 2. In caso contrario, modificalo in 2 e seleziona Salva.

Aggiungi l'URL di reindirizzamento

1. Con la registrazione aperta, vai a Autenticazione e seleziona Aggiungi una piattaforma.

   

2. Nel pannello Configura piattaforme seleziona Web.

   

3. In URL di reindirizzamento, aggiungi l'URL completo alla pagina in cui è ospitato il canvas della chat. Nella sezione Concessione implicita, seleziona le caselle di controllo Token di ID e Token di accesso.

4. Seleziona Configura per confermare le modifiche.

   

5. Vai ad Autorizzazioni API. Seleziona Concedi consenso amministratore per <nome del tenant> e quindi Sì.

   Importante

   Per evitare che gli utenti debbano fornire il consento per ciascuna applicazione, un amministratore globale, un amministratore dell'applicazione o un amministratore dell'applicazione cloud deve concedere il consenso a livello di tenant alle registrazioni della tua app.

   

Definire un ambito personalizzato per il tuo copilota

Definisci un ambito personalizzato esponendo un'API per la registrazione dell'app canvas nella registrazione dell'app di autenticazione. Gli ambiti ti consentono di determinare i ruoli utente e amministratore e i diritti di accesso.

Questo passaggio ti consente di creare una relazione di trust tra la registrazione dell'app di autenticazione per l'autenticazione e la registrazione dell'app per il canvas personalizzato.

1. Apri la registrazione dell'app che hai creato quando hai configurato l'autenticazione.

2. Vai ad Autorizzazioni API e assicurati che vengano aggiunte le autorizzazioni corrette per il tuo copilota. Seleziona Concedi consenso amministratore per <nome del tenant> e quindi Sì.

   Importante

   Per evitare che gli utenti debbano fornire il consento per ciascuna applicazione, un amministratore globale, un amministratore dell'applicazione o un amministratore dell'applicazione cloud deve concedere il consenso a livello di tenant alle registrazioni della tua app.

3. Vai a Esponi un'API e seleziona Aggiungi un ambito.

   

4. Immetti un nome per l'ambito, insieme alle informazioni di visualizzazione che dovrebbero essere mostrate agli utenti quando accedono alla schermata SSO. Seleziona Aggiungi ambito.

   

5. Seleziona Aggiungi applicazione client.

6. Inserisci l'ID applicazione (client) dalla pagina Panoramica per la registrazione dell'app canvas nel campo ID client. Seleziona la casella di controllo per l'ambito elencato che hai creato.

7. Seleziona Aggiungi applicazione.

Configurare l'autenticazione in Copilot Studio per abilitare SSO

L'URL di scambio token nella pagina di configurazione dell'autenticazione Copilot Studio viene utilizzato per scambiare il token OBO con il token di accesso richiesto tramite il bot framework.

Copilot Studio chiama Microsoft Entra ID per eseguire lo scambio effettivo.

1. Accedere a Copilot Studio.

2. Conferma di aver selezionato il copilota per il quale desideri abilitare l'autenticazione selezionando l'icona del copilota nel menu in alto e scegliendo il copilota corretto.

3. Nel menu di navigazione, in Impostazioni seleziona Sicurezza. Quindi, seleziona la scheda Autenticazione.

   

4. Immetti l'URI dell'ambito completo dal pannello Esporre un'API per la registrazione dell'app di autenticazione del copilota nel campo URL di scambio del token. L'URI è nel formato api://1234-4567/scope.name.

   

   

5. Quindi, seleziona Salva e pubblica il contenuto del copilota.

Configurare il codice HTML canvas personalizzato per abilitare SSO

Aggiorna la pagina del canvas personalizzato in cui si trova il copilota per intercettare la richiesta della scheda di accesso e scambiare il token OBO.

1. Configura la Microsoft Authentication Library (MSAL) aggiungendo il seguente codice in un tag <script> nella sezione <head>.

2. Aggiorna clientId con l'ID applicazione (client) per la registrazione dell'app canvas. Sostituisci <Directory ID> con l'ID directory (tenant). Ottieni questi ID dalla pagina Panoramica per la registrazione dell'app canvas.

   <head>
    <script>
      var clientApplication;
        (function () {
          var msalConfig = {
              auth: {
                clientId: '<Client ID [CanvasClientId]>',
                authority: 'https://login.microsoftonline.com/<Directory ID>'
              },
              cache: {
                cacheLocation: 'localStorage',
                storeAuthStateInCookie: false
              }
          };
          if (!clientApplication) {
            clientApplication = new Msal.UserAgentApplication(msalConfig);
          }
        } ());
    </script>
   </head>
   

3. Inserisci il seguente <script> nella sezione <body>. Questo script chiama un metodo per recuperare resourceUrl e scambia il token corrente con un token richiesto dal prompt di OAuth.

   <script>
   function getOAuthCardResourceUri(activity) {
     if (activity &&
          activity.attachments &&
          activity.attachments[0] &&
          activity.attachments[0].contentType === 'application/vnd.microsoft.card.oauth' &&
          activity.attachments[0].content.tokenExchangeResource) {
            // asking for token exchange with Microsoft Entra ID
            return activity.attachments[0].content.tokenExchangeResource.uri;
      }
   }
   
   function exchangeTokenAsync(resourceUri) {
     let user = clientApplication.getAccount();
      if (user) {
        let requestObj = {
          scopes: [resourceUri]
        };
        return clientApplication.acquireTokenSilent(requestObj)
          .then(function (tokenResponse) {
            return tokenResponse.accessToken;
            })
            .catch(function (error) {
              console.log(error);
            });
            }
            else {
            return Promise.resolve(null);
      }
   }
   </script>
   

4. Inserisci il seguente <script> nella sezione <body>. All'interno del metodo main, questo codice aggiunge un'azione condizionale al tuo store, con l'identificatore univoco del copilota. Genera anche un ID univoco come la tua variabile userId.

5. Aggiorna <COPILOT ID> con l'ID del tuo copilota. Puoi vedere l'ID del tuo copilota andando nella scheda Canali per il copilota che stai utilizzando e selezionando App per dispositivi mobili nel portale Copilot Studio.

   <script>
       (async function main() {
   
           // Add your COPILOT ID below 
           var BOT_ID = "<BOT ID>";
           var theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
           const {
               token
           } = await fetchJSON(theURL);
   
           var directline = await fetchJSON(regionalChannelSettingsURL).then(res=> res.channelUrlsById.directline); 
   
           const directLine = window.WebChat.createDirectLine({
               domain: `${directline}v3/directline`,
               token
           });
   
           var userID = clientApplication.account?.accountIdentifier != null ?
               ("Your-customized-prefix-max-20-characters" + clientApplication.account.accountIdentifier).substr(0, 64) :
               (Math.random().toString() + Date.now().toString()).substr(0, 64); // Make sure this will not exceed 64 characters 
           const store = WebChat.createStore({}, ({
               dispatch
           }) => next => action => {
               const {
                   type
               } = action;
               if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
                   dispatch({
                       type: 'WEB_CHAT/SEND_EVENT',
                       payload: {
                           name: 'startConversation',
                           type: 'event',
                           value: {
                               text: "hello"
                           }
                       }
                   });
                   return next(action);
               }
               if (action.type === 'DIRECT_LINE/INCOMING_ACTIVITY') {
                   const activity = action.payload.activity;
                   let resourceUri;
                   if (activity.from && activity.from.role === 'bot' &&
                       (resourceUri = getOAuthCardResourceUri(activity))) {
                       exchangeTokenAsync(resourceUri).then(function(token) {
                           if (token) {
                               directLine.postActivity({
                                   type: 'invoke',
                                   name: 'signin/tokenExchange',
                                   value: {
                                       id: activity.attachments[0].content.tokenExchangeResource.id,
                                       connectionName: activity.attachments[0].content.connectionName,
                                       token,
                                   },
                                   "from": {
                                       id: userID,
                                       name: clientApplication.account.name,
                                       role: "user"
                                   }
                               }).subscribe(
                                   id => {
                                       if (id === 'retry') {
                                           // copilot was not able to handle the invoke, so display the oauthCard
                                           return next(action);
                                       }
                                       // else: tokenexchange successful and we do not display the oauthCard
                                   },
                                   error => {
                                       // an error occurred to display the oauthCard
                                       return next(action);
                                   }
                               );
                               return;
                           } else
                               return next(action);
                       });
                   } else
                       return next(action);
               } else
                   return next(action);
           });
   
           const styleOptions = {
   
               // Add styleOptions to customize Web Chat canvas
               hideUploadButton: true
           };
   
           window.WebChat.renderWebChat({
                   directLine: directLine,
                   store,
                   userID: userID,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })().catch(err => console.error("An error occurred: " + err));
   </script>
   

Codice di esempio completo

Per ulteriori informazioni, puoi trovare il codice di esempio completo, con gli script condizionali MSAL e store già inclusi nel repository GitHub.