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 :

• Un enregistrement d’application d’authentification, qui permet l’authentification de l’utilisateur Microsoft Entra ID pour votre assistant
• Une inscription d’applications canevas 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 dans Configurer l’authentification des utilisateurs avec Microsoft Entra ID pour créer une enregistrement d’application d’authentification.

2. Créez une deuxième inscription de l’application pour servir d’inscription de l’application canevas.

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, dans le volet d’enregistrement de votre application d’authentification, accédez à Exposer 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 Paramètres, sélectionnez Sécurité, puis sélectionnez la vignette Authentification.

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

5. Cliquez sur Enregistrer.

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

1. Dans le portail Azure, dans le volet d’enregistrement de votre application d’authentification, accédez à Vue d’ensemble.

2. Copiez la valeur Identifiant d’application (client) sous Essentials.

3. Dans la barre de navigation, sélectionnez Gérer>Exposer une API.

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

5. Cliquez sur Enregistrer.

Configurer votre inscription d’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 assistant, puis sélectionnez Canaux.

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 référentiel GitHub de Copilot Studio pour créer une page web pour l’URL de redirection. Copiez le code à partir du référentiel GitHub et modifiez-le en suivant les instructions suivantes.

1. Accédez à la page Vue d’ensemble dans le portail Azure et copiez l’ID de l’application (client) et l’ID d’annuaire (client).

   

2. Pour configurer la bibliothèque d’authentification Microsoft (MSAL) :

   • Attribuez clientId à votre ID d’application (client).
   • Attribuez authority à https://login.microsoftonline.com/ et ajoutez votre ID du répertoire (client) à 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 assistant, si l’authentification unique (SSO) n’est pas configurée avec succès, vous êtes invité à vous connecter, ce qui vous donne un code de validation que vous devez copier dans la fenêtre de discussion.

   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é

• Enregistrement de l’application Azure

Présentation technique

L’illustration suivante montre comment un utilisateur s’est connecté sans recevoir d’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’assistant intercepte l’invite de connexion et demande un jeton On-Behalf-Of (OBO) à 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 :

• Une pour votre assistant, pour activer l’authentification de l’utilisateur avec Microsoft Entra ID.
• Une pour votre canevas personnalisé, pour activer l’authentification SSO.

Créer un enregistrement d’application Azure pour le canevas de l’agent

1. Connectez-vous au portail Azure.

2. Accédez à Inscriptions d’applications, soit en sélectionnant l’icône ou en effectuant une recherche 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 dont vous inscrivez le canevas et d’inclure « canevas » pour le distinguer de l’inscription de l’application d’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. Dans Types de comptes pris en charge, sélectionnez Comptes dans n’importe quel client organisationnel (tout répertoire Microsoft Entra ID – partagé au sein d’une architecture mutualisée) 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 Inscrire.

   

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 étendue personnalisée en exposant une API pour l’inscription d’application canevas dans l’inscription de l’application d’authentification. Les champs 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 d’authentification pour l’authentification et l’inscription d’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 l’étendue, ainsi que les informations d’affichage qui doivent être présentées aux utilisateurs lorsqu’ils affichent 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 SSO

L’URL d’échange de jetons dans la page de configuration de l’authentification Copilot Studio est utilisée pour échanger le jeton OBO contre le jeton d’accès demandé via Bot Framework.

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 du canal Est dans le 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 la bibliothèque d’authentification Microsoft (MSAL) en ajoutant le code suivant dans une balise <script> dans la section <head>.

2. Mettez à jour clientId avec l’ID d’application (client) pour l’inscription de l’application canevas. Remplacez <Directory ID> par l’ID du répertoire (locataire). Vous pouvez obtenir ces ID dans la page Aperçu de l’inscription de l’application canevas.

   <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 assistant dans Copilot Studio, accédez à la page Canaux de votre assistant, puis sélectionnez 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 pouvez trouver l’exemple de code complet, avec les scripts conditionnels store et MSAL inclus, dans notre référentiel GitHub.