Activer l’authentification unique dans un complément Office à l’aide de l’authentification d’application imbriquée (préversion)

Vous pouvez utiliser la bibliothèque MSAL.js avec l’authentification d’application imbriquée pour utiliser l’authentification unique à partir de votre complément Office. L’utilisation de l’authentification d’application imbriquée offre plusieurs avantages par rapport au flux On-Behalf-Of (OBO).

• Vous devez uniquement utiliser la bibliothèque MSAL.js et n’avez pas besoin de la getAccessToken fonction dans Office.js.
• Vous pouvez appeler des services tels que Microsoft Graph avec un jeton d’accès à partir de votre code client en tant que spa. Il n’est pas nécessaire d’utiliser un serveur de niveau intermédiaire.
• Vous pouvez utiliser le consentement incrémentiel et dynamique pour les étendues.
• Vous n’avez pas besoin de préautoriser vos hôtes (par exemple, Teams, Office) pour appeler vos points de terminaison.

Comptes et hôtes pris en charge par NAA

NAA prend en charge les comptes Microsoft et les identités Microsoft Entra ID (professionnel/scolaire). Il ne prend pas en charge Azure Active Directory B2C pour les scénarios de gestion des identités entreprise-consommateur. Le tableau suivant décrit la prise en charge actuelle par plateforme. Tout ce qui est répertorié comme « Bientôt disponible » sera pris en charge au moment où NAA sera mis à la disposition générale.

Inscrire votre application monopage

Vous devez créer une inscription Microsoft Azure App pour votre complément sur le Portail Azure. L’inscription de l’application doit avoir au minimum :

• Un nom
• Type de compte pris en charge
• Une redirection SPA

Si votre complément nécessite une inscription d’application supplémentaire au-delà de NAA et de l’authentification unique, consultez Application monopage : inscription d’application.

Ajouter un répartiteur approuvé via la redirection SPA

Pour activer NAA, l’inscription de votre application doit inclure un URI de redirection spécifique pour indiquer au Plateforme d'identités Microsoft que votre complément se permet d’être réparti par des hôtes pris en charge. L’URI de redirection de l’application doit être de type Application monopage et être conforme au schéma suivant.

brk-multihub://your-add-in-domain

Par exemple, si vous testez votre complément sur le port 3000 sur le serveur localhost, vous devez utiliser brk-multihub://localhost:3000 comme valeur de redirection.

Les groupes de répartiteur approuvés sont dynamiques par conception et peuvent être mis à jour à l’avenir pour inclure des hôtes supplémentaires où votre complément peut utiliser des flux NAA. Actuellement, le groupe brk-multihub comprend Office Word, Excel, PowerPoint, Outlook et Teams (lorsque Office est activé à l’intérieur).

Configurer la configuration MSAL pour utiliser NAA

Configurez votre complément pour utiliser NAA en appelant la createNestablePublicClientApplication fonction dans MSAL. MSAL retourne une application cliente publique qui peut être imbriquée dans un hôte d’application natif (par exemple, Outlook) pour acquérir des jetons pour votre application.

Les étapes suivantes montrent comment activer NAA dans le taskpane.js fichier ou taskpane.ts dans un projet créé avec yo office (projet du volet Office de complément Office ).

1. Ajoutez le @azure/msal-browser package à la dependencies section du package.json fichier pour votre projet. Pour plus d’informations sur ce package, consultez Bibliothèque d’authentification Microsoft pour JavaScript (MSAL.js) pour les applications Browser-Based Single-Page. Nous vous recommandons d’utiliser la dernière version du package (au moment de la dernière mise à jour de l’article, il s’agissait de la version 3.26.0).

   "dependencies": {
       "@azure/msal-browser": "^3.26.0",
       ...
   

2. Enregistrez et exécutez npm install pour installer @azure/msal-browser.

3. Ajoutez le code suivant en haut du taskpane.js fichier ou taskpane.ts . Cette opération importera la bibliothèque de navigateur MSAL.

   import { createNestablePublicClientApplication } from "@azure/msal-browser";
   

Initialiser l’application cliente publique

Ensuite, vous devez initialiser MSAL et obtenir une instance de l’application cliente publique. Il est utilisé pour obtenir des jetons d’accès si nécessaire. Nous vous recommandons de placer le code qui crée l’application cliente publique dans la Office.onReady méthode .

• Dans votre Office.onReady fonction, ajoutez un appel à createNestablePublicClientApplication comme indiqué ci-dessous. Remplacez l’espace Enter_the_Application_Id_Here réservé par l’ID d’application Azure que vous avez enregistré précédemment.

  let pca = undefined;
  Office.onReady(async (info) => {
    if (info.host) {
      document.getElementById("sideload-msg").style.display = "none";
      document.getElementById("app-body").style.display = "flex";
      document.getElementById("run").onclick = run;
  
      // Initialize the public client application
      pca = await createNestablePublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
          authority: "https://login.microsoftonline.com/common"
        },
      });
    }
  });
  

Acquérir votre premier jeton

Les jetons acquis par MSAL.js via NAA seront émis pour votre ID d’inscription d’application Azure. Dans cet exemple de code, vous obtenez un jeton pour microsoft API Graph. Si l’utilisateur dispose d’une session active avec Microsoft Entra ID le jeton est acquis en mode silencieux. Si ce n’est pas le cas, la bibliothèque invite l’utilisateur à se connecter de manière interactive. Le jeton est ensuite utilisé pour appeler le API Graph Microsoft.

Les étapes suivantes montrent le modèle à utiliser pour l’acquisition d’un jeton.

1. Spécifiez vos étendues. NAA prend en charge le consentement incrémentiel et dynamique. Demandez donc toujours les étendues minimales nécessaires pour que votre code termine sa tâche.
2. Appel acquireTokenSilent. Cela permet d’obtenir le jeton sans nécessiter l’interaction de l’utilisateur.
3. En acquireTokenSilent cas d’échec, appelez acquireTokenPopup pour afficher une boîte de dialogue interactive pour l’utilisateur. acquireTokenSilent peut échouer si le jeton a expiré ou si l’utilisateur n’a pas encore consenti à toutes les étendues demandées.

Le code suivant montre comment implémenter ce modèle d’authentification dans votre propre projet.

1. Remplacez la run fonction dans taskpane.js ou taskpane.ts par le code suivant. Le code spécifie les étendues minimales nécessaires pour lire les fichiers de l’utilisateur.

   async function run() {
   // Specify minimum scopes needed for the access token.
   const tokenRequest = {
     scopes: ["Files.Read", "User.Read", "openid", "profile"],
   };
   let accessToken = null;
   
   // TODO 1: Call acquireTokenSilent.
   
   // TODO 2: Call acquireTokenPopup.
   
   // TODO 3: Log error if token still null.
   
   // TODO 4: Call the Microsoft Graph API.
   
   }
   

2. Remplacez TODO 1 par le code suivant. Ce code appelle acquireTokenSilent pour obtenir le jeton d’accès.

   try {
     console.log("Trying to acquire token silently...");
     const userAccount = await pca.acquireTokenSilent(tokenRequest);
     console.log("Acquired token silently.");
     accessToken = userAccount.accessToken;
   } catch (error) {
     console.log(`Unable to acquire token silently: ${error}`);
   }
   

3. Remplacez TODO 2 par le code suivant. Ce code vérifie si le jeton d’accès est acquis. Si ce n’est pas le cas, il tente d’obtenir de manière interactive le jeton d’accès en appelant acquireTokenPopup.

   if (accessToken === null) {
     // Acquire token silent failure. Send an interactive request via popup.
     try {
       console.log("Trying to acquire token interactively...");
       const userAccount = await pca.acquireTokenPopup(tokenRequest);
       console.log("Acquired token interactively.");
       accessToken = userAccount.accessToken;
     } catch (popupError) {
       // Acquire token interactive failure.
       console.log(`Unable to acquire token interactively: ${popupError}`);
     }
   }
   

4. Remplacez TODO 3 par le code suivant. Si la connexion silencieuse et interactive a échoué, journalisez l’erreur et retournez.

   // Log error if both silent and popup requests failed.
   if (accessToken === null) {
     console.error(`Unable to acquire access token.`);
     return;
   }
   

Appeler une API

Après avoir acquis le jeton, utilisez-le pour appeler une API. L’exemple suivant montre comment appeler le API Graph Microsoft en appelant fetch avec le jeton attaché dans l’en-tête Authorization.

• Remplacez TODO 4 par le code suivant.

  // Call the Microsoft Graph API with the access token.
  const response = await fetch(
    `https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name&$top=10`,
    {
      headers: { Authorization: accessToken },
    }
  );
  
  if (response.ok) {
    // Write file names to the console.
    const data = await response.json();
    const names = data.value.map((item) => item.name);
  
    // Be sure the taskpane.html has an element with Id = item-subject.
    const label = document.getElementById("item-subject");
  
    // Write file names to task pane and the console.
    const nameText = names.join(", ");
    if (label) label.textContent = nameText;
    console.log(nameText);
  } else {
    const errorText = await response.text();
    console.error("Microsoft Graph call failed - error text: " + errorText);
  }
  

Une fois que tout le code précédent est ajouté à la run fonction, assurez-vous qu’un bouton du volet Office appelle la run fonction. Vous pouvez ensuite charger une version test du complément et essayer le code.

Qu’est-ce que l’authentification d’application imbriquée ?

L’authentification d’application imbriquée permet l’authentification unique pour les applications imbriquées dans les applications Microsoft prises en charge. Par exemple, Excel sur Windows exécute votre complément dans une vue web. Dans ce scénario, votre complément est une application imbriquée s’exécutant dans Excel, qui est l’hôte. NAA prend également en charge les applications imbriquées dans Teams. Par exemple, si un onglet Teams héberge Excel et que votre complément est chargé, il est imbriqué dans Excel, qui est également imbriqué dans Teams. Là encore, NAA prend en charge ce scénario imbriqué et vous pouvez accéder à l’authentification unique pour obtenir l’identité de l’utilisateur et les jetons d’accès de l’utilisateur connecté.

Meilleures pratiques

Nous vous recommandons les meilleures pratiques suivantes lors de l’utilisation de MSAL.js avec NAA.

Utiliser l’authentification silencieuse dans la mesure du possible

MSAL.js fournit la méthode qui gère le acquireTokenSilent renouvellement des jetons en effectuant des demandes de jeton silencieuses sans demander à l’utilisateur. La méthode recherche d’abord un jeton mis en cache valide. Si elle n’en trouve pas, la bibliothèque effectue la demande en mode silencieux pour Microsoft Entra ID et, s’il existe une session utilisateur active, un nouveau jeton est retourné.

Dans certains cas, la acquireTokenSilent tentative d’obtention du jeton par la méthode échoue. Par exemple, il y a une session utilisateur expirée avec Microsoft Entra ID ou une modification de mot de passe par l’utilisateur, ce qui nécessite une interaction de l’utilisateur. En cas d’échec de acquireTokenSilent, vous devez appeler la méthode de jeton interactif acquireTokenPopup .

Disposer d’un secours quand NAA n’est pas pris en charge

Bien que nous nous efforçions de fournir un haut degré de compatibilité avec ces flux dans l’écosystème Microsoft, votre complément peut être chargé dans un hôte Office plus ancien qui ne prend pas en charge NAA. Dans ce cas, votre complément ne prend pas en charge l’authentification unique transparente et vous devrez peut-être revenir à une autre méthode d’authentification de l’utilisateur. En général, vous pouvez utiliser le modèle d’authentification MSAL SPA avec l’API de boîte de dialogue Office JS.

Utilisez le code suivant pour case activée si NAA est pris en charge lors du chargement de votre complément.

   Office.context.requirements.isSetSupported("NestedAppAuth", "1.1");

Pour plus d’informations, consultez les ressources suivantes.

• Exemple Outlook : Comment revenir en arrière et prendre en charge Internet Explorer 11
• Authentifiez et autorisez avec l’API de boîte de dialogue Office.
• Exemple d’identité Microsoft pour SPA et JavaScript
• Exemples d’identités Microsoft pour différents types d’applications et infrastructures

API MSAL.js prises en charge par NAA

Le tableau suivant indique les API prises en charge lorsque NAA est activé dans la configuration MSAL.

Rapports de sécurité

Si vous rencontrez un problème de sécurité avec nos bibliothèques ou services, signalez-le avec secure@microsoft.com autant de détails que vous pouvez fournir. Votre soumission peut être éligible à une prime par le biais du programme Microsoft Bounty . Ne publiez pas de problèmes de sécurité sur GitHub ou tout autre site public. Nous vous contacterons peu de temps après la réception de votre rapport de problème. Nous vous encourageons à recevoir de nouvelles notifications d’incident de sécurité en consultant les notifications de sécurité techniques de Microsoft pour vous abonner aux alertes d’avis de sécurité.

Exemples de code

Voir aussi

• QUESTIONS FRÉQUENTES (FAQ) SUR NAA