Configurer l’authentification unique avec Microsoft Entra ID

Créer des inscriptions d’applications pour votre site web personnalisé

Pour activer l’authentification SSO, vous devez créer deux inscriptions d’application distinctes :

• Inscription d'application d'authentification, qui permet l'authentification des utilisateurs Microsoft Entra ID pour votre agent
• Une inscription d'application Canvas qui active l’authentification unique (SSO) pour votre page web personnalisée

Pour des raisons de sécurité, nous vous déconseillons de réutiliser le même enregistrement d’application pour votre agent et votre site web personnalisé.

1. Suivez les instructions de Configurer l’authentification utilisateur avec Microsoft Entra ID pour créer une inscription d’application d’authentification.

2. Créez un deuxième enregistrement d'application à utiliser comme enregistrement de votre application canvas.

Ajouter une URL d’échange de jetons

Pour mettre à jour les paramètres d’authentification Microsoft Entra ID dans Copilot Studio, vous devez ajouter l’URL d’échange de jetons pour autoriser votre application et Copilot Studio à partager des informations.

1. Dans le portail Azure sur la page d'inscription de votre application d'authentification, accédez à Expose une API.

2. Sous Étendues, sélectionnez l’icône Copier dans le Presse-papier.

3. Dans Copilot Studio, dans le menu de navigation sous Settings, sélectionnez Security, puis sélectionnez la vignette Authentication.

4. Pour URL d’échange de jeton (obligatoire pour SSO), collez le scope que vous avez copié précédemment.

5. Cliquez sur Enregistrer.

Configurer votre ID client d’application canevas pour exposer un menu API

1. Dans le portail Azure sur la page d’inscription de votre application d’authentification, accédez à Overview.

2. Copiez la valeur de l’ID d’application (client) sous Essentials.

3. Dans la barre de navigation, sélectionnez Gérer l’exposition>d’une API.

4. Sous Applications client autorisées, sélectionnez Ajouter une application client, puis collez l’identifiant client copié.

5. Cliquez sur Enregistrer.

Configurez l’enregistrement de votre application canevas

1. Après avoir créé l’inscription d’applications canevas, accédez à Authentification, puis sélectionnez Ajouter une plateforme.

2. Sous Configurations de plateforme, sélectionnez Ajouter une plateforme, puis sélectionnez SPA.

3. Sous URI de redirection, entrez l’URL de votre page Web ; par exemple, http://contoso.com/index.html.

   

4. Sous la section Octroi implicite et flux hybrides, activez les deux Jetons d’accès (utilisés pour les flux implicites) et Jetons d’ID (utilisés pour les flux implicites et hybrides).

5. Sélectionnez Configurer.

Trouver l’URL du point de terminaison du jeton de votre agent

1. Dans Copilot Studio, ouvrez votre agent, puis sélectionnez Channels.

2. Sélectionnez Application mobile.

3. Sous Point de terminaison de jeton, sélectionnez Copier.

   

Configurer SSO dans votre page Web

Utilisez le code fourni dans le dépôt Copilot Studio GitHub pour créer une page web pour l’URL de redirection. Copiez le code du dépôt GitHub et modifiez-le à l’aide des instructions suivantes.

1. Accédez à la page Overview dans le portail Azure et copiez l’ID Application (client) et l’ID Directory (tenant) à partir de l’inscription de votre application Canvas.

   

2. Pour configurer le Microsoft Authentication Library (MSAL) :

   • Attribuez clientId à votre ID d’application (client).
   • Attribuez authority à https://login.microsoftonline.com/ et ajoutez votre ID de l'annuaire (locataire) à la fin.

   Par exemple :

   var clientApplication;
       (function (){
       var msalConfig = {
           auth: {
               clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
               authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'     
           },
   

3. Définissez la variable theURL sur l’URL du point de terminaison du jeton que vous avez copiée précédemment. Par exemple :

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

4. Modifiez la valeur de userId pour inclure un préfixe personnalisé. Par exemple :

   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. Enregistrez vos modifications.

6. Vérifiez que vous avez correctement configuré l’authentification unique.

   Lorsque vous testez votre agent, si l’authentification unique n’est pas correctement configurée, vous êtes invité à vous connecter, ce qui vous donne un code de validation que vous devez copier dans la fenêtre de conversation.

   Si vous voyez une invite de connexion, vérifiez que vous avez correctement effectué les étapes 1 à 5 de cette procédure. Si l’authentification unique (SSO) est correctement configurée, vous n’êtes pas invité à vous connecter.

   Note

   Le code du dépôt GitHub nécessite que les utilisateurs sélectionnent le bouton de connexion. En production, vous pouvez remplacer la fonctionnalité de bouton par un événement plus approprié, comme la navigation vers une page.

Contenu associé

• Azure App Inscription

Présentation technique

L’illustration suivante montre comment un utilisateur est connecté sans voir une invite de connexion (SSO) dans Copilot Studio :

1. L’utilisateur de l’agent entre une phrase qui déclenche une rubrique de connexion. La rubrique de connexion est conçue pour connecter l’utilisateur et utiliser son jeton authentifié(variable User.AccessToken).

2. Copilot Studio envoie une invite de connexion pour permettre à l’utilisateur de se connecter avec son fournisseur d’identité configuré.

3. Le canevas personnalisé de l'agent intercepte l'invite de connexion et demande un jeton OBO (on-behalf-of) à partir de Microsoft Entra ID. Le canevas envoie le jeton à l’agent.

4. À réception du jeton OBO, l’agent échange le jeton OBO contre un « jeton d’accès » et remplit la variable AuthToken en utilisant la valeur du jeton d’accès. La variable IsLoggedIn est également définie à ce moment-là.

Créer une inscription d’application dans Microsoft Entra ID pour votre canevas personnalisé

Pour activer l’authentification SSO, vous avez besoin de deux inscriptions d’application distinctes :

• Un pour votre agent afin de permettre l'authentification des utilisateurs avec Microsoft Entra ID.
• Une pour votre canevas personnalisé, pour activer l’authentification unique (SSO).

Créer un enregistrement d'application pour la toile de l'agent

1. Connectez-vous au portail Azure.

2. Accédez à App registrations, en sélectionnant l’icône ou en recherchant dans la barre de recherche supérieure.

   

3. Sélectionnez Nouvelle inscription.

   

4. Entrez un nom pour l’inscription. Il peut être utile d'utiliser le nom de l'agent pour lequel vous enregistrez le canevas et d'inclure « canevas » pour le distinguer de l'enregistrement de l'application pour l'authentification.

   Par exemple, si votre agent s’appelle « Aide aux ventes Contoso », vous pouvez nommer l’inscription de l’application « ContosoSalesCanvas » ou quelque chose de similaire.

5. Sous Types de comptes pris en charge, sélectionnez Accounts dans n’importe quel locataire organisationnel (n’importe quel annuaire Microsoft Entra ID - Multilocataire) et comptes Microsoft personnels (par exemple, Skype, Xbox).

6. Laissez la section URI de redirection vide pour l’instant, car vous entrez ces informations dans les étapes suivantes. Sélectionnez Inscription.

   

7. Une fois l’inscription terminée, elle ouverte dans la page Aperçu. Aller à Manifeste. Confirmez que accessTokenAcceptedVersion est réglé sur 2. Si ce n’est pas le cas, remplacez-le par 2, puis sélectionnez Enregistrer.

Ajouter l’URL de redirection

1. Les inscriptions étant ouvertes, rendez-vous sur Authentification, puis sélectionnez Ajouter une plateforme.

   

2. Dans le panneau Configurer des plateformes, sélectionnez Web.

   

3. Sous URI de redirections, ajoutez l’URL complète de la page où votre canevas de chat est hébergé. Sous la section Octroi implicite, cochez les cases Jetons d’identification et Jetons d’accès.

4. Sélectionnez Configurer pour confirmer vos modifications.

   

5. Accédez à Autorisations API. Sélectionnez Accorder le consentement de l’administrateur pour <votre nom de locataire>, puis Oui.

   Important

   Pour éviter aux utilisateurs d’avoir à accorder leur consentement à chaque application, une personne à laquelle au moins le rôle Administrateur d’application ou Administrateur d’application cloud est affectée peut accorder son consentement à l’échelle du locataire à vos inscriptions d’applications.

   

Définir une étendue personnalisée pour votre agent

Définissez une portée personnalisée en exposant une API pour l'enregistrement de l'application canvas dans celui de l'application d'authentification. Les périmètres vous permettent de déterminer les rôles d’utilisateur et d’administrateur, ainsi que les droits d’accès.

Cette étape crée une relation de confiance entre l'inscription de l'application pour l'authentification et l'inscription de l'application pour votre canevas personnalisé.

1. Ouvrez l’inscription d’application que vous avez créée lorsque vous avez configuré l’authentification.

2. Accédez à Autorisations API et assurez-vous que les autorisations appropriées sont ajoutées pour votre agent. Sélectionnez Accorder le consentement de l’administrateur pour <votre nom de locataire>, puis Oui.

   Important

   Pour éviter aux utilisateurs d’avoir à accorder leur consentement à chaque application, une personne à laquelle au moins le rôle Administrateur d’application ou Administrateur d’application cloud est affectée peut accorder son consentement à l’échelle du locataire à vos inscriptions d’applications.

3. Accédez à Exposer une API et sélectionnez Ajouter une étendue.

   

4. Entrez un nom pour le périmètre, ainsi que les informations d'affichage qui doivent être présentées aux utilisateurs lorsqu'ils consultent l'écran SSO. Sélectionnez Ajouter une étendue.

   

5. Sélectionnez Ajouter une application cliente.

6. Entrez l’ID d’application (client) issu de la page Aperçu de l’inscription de l’application canevas dans le champ ID client. Cochez la case correspondant à l’étendue répertoriée que vous avez créée.

7. Sélectionnez Ajouter une application.

Configurer l’authentification dans Copilot Studio pour activer l’authentification unique (SSO)

L'URL Token Exchange dans la page de configuration de l'authentification de Copilot Studio est utilisée pour échanger le jeton OBO contre le jeton d'accès demandé via le framework de bot.

Copilot Studio appelle Microsoft Entra ID pour effectuer l’échange réel.

1. Connectez-vous à Copilot Studio.

2. Confirmez que vous avez sélectionné l’assistant pour lequel vous souhaitez activer l’authentification en sélectionnant l’icône d’assistant dans le menu supérieur et en choisissant l’assistant approprié.

3. Dans le menu de navigation, sous Paramètres, sélectionnez Sécurité. Ensuite, sélectionnez la carte Authentification.

   

4. Entrez l’URI de l’étendue complète à partir de la page Exposer une API pour l’enregistrement de l’application d’authentification de l’assistant dans le domaine URL d’échange de jetons. L’URI est au format api://1234-4567/scope.name.

   

   

5. Sélectionnez Enregistrer, puis publiez le contenu de l’agent.

Configurer le code HTML de votre canevas personnalisé pour activer l’authentification SSO

Mettez à jour la page du canevas personnalisé où se trouve l’assistant pour intercepter la demande de fiche de connexion et échanger le jeton OBO.

1. Configurez le Microsoft Authentication Library (MSAL) en ajoutant le code suivant dans une balise <script> dans votre section <head>.

2. Mettez à jour clientId avec l’ID de l’application (client) pour l’enregistrement de l’application de type canevas. Remplacez par l’ID de locataire (tenant) du répertoire . Vous pouvez obtenir ces identifiants dans la page Aperçu de l’inscription de l’application 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. Insérez le <script> suivant dans la section <body>. Ce script appelle une méthode pour récupérer le resourceUrl et échanger votre jeton actuel contre un jeton demandé par l’invite 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. Insérez le <script> suivant dans la section <body>. Dans la méthode main, ce code ajoute une condition à votre store, avec l’identificateur unique de votre agent. Il génère également un ID unique considéré comme étant votre variable userId.

5. Mettez à jour <BOT ID> avec l’ID de votre agent. Pour afficher l'ID de votre agent dans Copilot Studio, accédez à la page Channels de votre agent, puis sélectionnez l'application Mobile.

   <script>
       (async function main() {
   
           // Add your BOT 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>
   

Exemple de code complet

Pour plus d’informations, vous trouverez l’exemple de code complet, avec MSAL et stockez des scripts conditionnels déjà inclus à notre dépôt GitHub.