Configurare Single Sign-On in con Microsoft Entra ID

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 Microsoft Entra l'autenticazione utente ID per il tuo agente
• Una registrazione dell'app canvas che abilita SSO per la tua pagina web personalizzata

Per motivi di sicurezza, sconsigliamo di riutilizzare la stessa registrazione dell'app sia per agente che per il tuo 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 del token agente endpoint

1. In Copilot Studio, apri agente e poi 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.

    (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.

Prova il tuo agente usando 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 agente e incolla il codice di convalida nella conversazione agente.

Contenuto correlato

• Registrazione dell'app di Azure

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 agente inserisce una frase che attiva un accesso argomento. 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. La tela personalizzata di agente intercetta la richiesta di accesso e richiede un token per conto di (OBO) da Microsoft Entra ID. La tela invia il token a agente.

4. Dopo aver ricevuto il token OBO, agente scambia il token OBO con un "token di accesso" e compila la variabile AuthToken utilizzando il valore di 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:

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

Crea una registrazione dell'app per la tela di agente

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 usare il nome del agente di cui stai registrando la canvas e includere "canvas" per separarlo dalla registrazione dell'app per l'autenticazione.

   Ad esempio, se il tuo agente si chiama "Contoso sales help", potresti chiamare la registrazione dell'app "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.

   

Definisci un ambito personalizzato per il tuo agente

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 su Autorizzazioni API e assicurati che siano aggiunte le autorizzazioni corrette per il tuo agente. 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 l'agente per cui desideri abilitare l'autenticazione selezionando l'icona agente nel menu in alto e scegliendo l'agente corretto.

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

   

4. Inserisci l'URI completo dalla sezione Esponi un'API per la registrazione dell'app di autenticazione agente nel campo URL di scambio token . L'URI è nel formato api://1234-4567/scope.name.

   

   

5. Seleziona Salva e poi pubblica il contenuto agente.

Configurare il codice HTML canvas personalizzato per abilitare SSO

Aggiornare la pagina canvas personalizzata in cui si trova agente per intercettare la richiesta di accesso scheda 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 una condizione al tuo store, con l'identificatore univoco del tuo agente. Genera anche un ID univoco come la tua variabile userId.

5. Aggiorna <COPILOT ID> con l'ID del tuo agente. Puoi vedere l'ID del tuo agente andando alla scheda Canali del agente che stai utilizzando e selezionando App mobile sul Copilot Studio portale.

   <script>
       (async function main() {
   
           // Add your AGENT 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') {
                                           // The agent 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.