Authentification des applications imbriquées

NAA est un nouveau protocole d’authentification pour les spas incorporés dans les environnements hôtes, tels que Teams, Outlook et Microsoft 365. Il simplifie le processus d’authentification pour faciliter l’authentification unique (SSO) entre les applications imbriquées dans les applications hôtes prises en charge. Le modèle NAA prend en charge une identité principale pour l’application hôte qui inclut plusieurs identités d’application pour les applications imbriquées. Microsoft utilise ce modèle dans les onglets Teams, les applications personnelles et les compléments Office.

Le modèle NAA offre plusieurs avantages par rapport au flux On-Behalf-Of (OBO) :

• NAA vous oblige à utiliser uniquement la bibliothèque MSAL.js. Vous n’avez pas besoin d’utiliser la fonction dans la getAuthToken bibliothèque de client JavaScript Teams (TeamsJS).

• 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 (autorisations).

• Vous n’avez pas besoin de préautoriser vos hôtes, tels que Teams ou Microsoft 365, pour appeler vos points de terminaison.

  Le tableau suivant décrit la différence entre Teams Microsoft Entra l’authentification unique et NAA :

  Étapes requises pour le développement	Authentification unique Traditionnelle Teams Entra	NAA
  Exposer l’URI de redirection	Obligatoire	Obligatoire
  Inscrire l’API dans l’ID Microsoft Entra	Requis
  Définir une étendue personnalisée dans Microsoft Entra ID	Requis
  Autoriser les applications clientes Teams	Requis
  Réviser le manifeste d’application (précédemment appelé manifeste d’application Teams)	Requis	Recommandé*
  Acquérir un jeton d’accès via le Kit de développement logiciel (SDK) TeamsJS	Requis
  Solliciter le consentement de l’utilisateur pour obtenir plus d’autorisations	Requis
  Effectuer un échange OBO sur le serveur	Requis

• L’administrateur informatique peut bloquer l’application ou donner son consentement à certaines autorisations uniquement pour l’application dans Microsoft Entra ID. Pour l’éviter, vous devez inclure l’ID d’application et la ressource par défaut dans le manifeste de l’application pour que l’administrateur approuve les autorisations dans le Centre d’administration Teams.

Cas d’usage pour NAA

Configurer NAA

Pour configurer l’authentification imbriquée, procédez comme suit :

1. Inscrire votre spa
2. Ajouter des répartiteurs approuvés
3. Initialiser l’application cliente publique
4. Acquérir votre premier jeton
5. Appeler une API

Inscrire votre spa

Vous devez créer une inscription d’application ID Microsoft Entra pour votre complément sur Portail Azure. L’inscription de l’application doit avoir un nom, un type de compte pris en charge et une redirection SPA. Après l’inscription de votre application, Portail Azure génère un ID d’inscription d’application Microsoft Entra. Si votre complément nécessite une inscription d’application supplémentaire au-delà de NAA et de l’authentification unique, consultez Inscrire votre application monopage.

Ajouter des répartiteurs approuvés

Pour configurer l’authentification d’application imbriquée, votre application doit configurer activement un URI de redirection pour votre application. L’URI de redirection indique au Plateforme d'identités Microsoft que votre application peut être répartie par des hôtes pris en charge. L’URI de redirection de l’application doit être de type Application monopage et conforme au schéma suivant :

brk-multihub://<your_domain>

où :

• brk-multihub permet à votre authentification d’être répartie par tous les hôtes pris en charge par Microsoft 365 qu’elle est configurée pour s’exécuter dans tels que Teams, Outlook ou Microsoft365.com.
• < > your_domain est le nom de domaine complet où votre application est hébergée. Par exemple, brk-multihub ://contoso.com.

Votre domaine doit inclure uniquement l’origine et non ses sous-chemins. Par exemple :

✔️ brk-multihub ://myapp.teams.microsoft.com
❌ brk-multihub ://myapp.teams.microsoft.com/go

Pour plus d’informations sur la mise à niveau de votre application Teams pour qu’elle s’exécute dans Outlook et Microsoft365.com, voir Étendre les applications Teams dans Microsoft 365.

Initialiser l’application cliente publique

Initialisez MSAL et obtenez une instance de l’application cliente publique pour obtenir des jetons d’accès, si nécessaire.

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

const msalConfig = {
  auth: {
    clientId: "your_client_id",
    authority: "https://login.microsoftonline.com/{your_tenant_id}",
    supportsNestedAppAuth: true
  },
};

let pca: IPublicClientApplication;

export function initializePublicClient() {
  console.log("Starting initializePublicClient");
  return createNestablePublicClientApplication(msalConfig).then(
    (result) => {
      console.log("Client app created");
      pca = result;
      return pca;
    }
  );
}

Acquérir votre premier jeton

Les jetons acquis par MSAL.js via l’authentification d’application imbriquée sont émis pour votre ID d’inscription d’application Microsoft Entra. MSAL.js gère l’acquisition de jetons pour l’authentification utilisateur. Il tente d’obtenir un jeton d’accès en mode silencieux. En cas d’échec, il invite l’utilisateur à donner son consentement. Le jeton est ensuite utilisé pour appeler les ressources microsoft API Graph ou d’autres ressources protégées par l’ID Microsoft Entra. Contrairement au flux OBO, vous n’avez pas besoin de préautoriser vos hôtes pour appeler les points de terminaison.

Pour acquérir un jeton, procédez comme suit :

1. Utilisez MSAL.js pour acquérir des jetons pour votre ID d’application. Pour plus d’informations, consultez Acquérir et utiliser un jeton d’accès.

2. Utilisez l’API getActiveAccount pour vérifier s’il existe un compte actif pour appeler le publicClientApplication. S’il n’existe aucun compte actif, essayez d’en récupérer un à partir du cache avec getAccount, à l’aide de paramètres de filtre supplémentaires, tels que tenantID, homeAccountIdet loginHint à partir de l’interface de contexte.

   Remarque

   La homeAccountId propriété est équivalente à userObjectId dans TeamsJS.

3. Appelez publicClientApplication.acquireTokenSilent(accessTokenRequest) pour acquérir le jeton en mode silencieux sans intervention de l’utilisateur. accessTokenRequest spécifie les étendues pour lesquelles le jeton d’accès est demandé. NAA prend en charge le consentement incrémentiel et dynamique. Veillez à toujours demander les étendues minimales nécessaires pour que votre code termine sa tâche.

4. Si aucun compte n’est disponible, MSAL.js retourne un InteractionRequiredAuthError. Appelez publicClientApplication.acquireTokenPopup(accessTokenRequest) 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 consenti à toutes les étendues demandées.

   L’extrait de code suivant montre un exemple d’accès à un jeton :

   
     // MSAL.js exposes several account APIs, logic to determine which account to use is the responsibility of the developer
     const account = publicClientApplication.getActiveAccount();
   
     const accessTokenRequest = {
     scopes: ["user.read"],
     account: account,
     };
   
     publicClientApplication
       .acquireTokenSilent(accessTokenRequest)
       .then(function (accessTokenResponse) {
         // Acquire token silent success
         let accessToken = accessTokenResponse.accessToken;
         // Call your API with token
         callApi(accessToken);
       })
       .catch(function (error) {
         //Acquire token silent failure, and send an interactive request
         if (error instanceof InteractionRequiredAuthError) {
           publicClientApplication
             .acquireTokenPopup(accessTokenRequest)
             .then(function (accessTokenResponse) {
               // Acquire token interactive success
               let accessToken = accessTokenResponse.accessToken;
               // Call your API with token
               callApi(accessToken);
             })
             .catch(function (error) {
               // Acquire token interactive failure
               console.log(error);
             });
         }
         console.log(error);
       });
   
   

Appeler une API

Une fois le jeton reçu, utilisez-le pour appeler l’API. Cela garantit que l’API est appelée avec un jeton valide pour effectuer des demandes authentifiées sur le serveur.

L’exemple suivant montre comment effectuer une demande authentifiée auprès de Microsoft API Graph pour accéder aux données Microsoft 365 :

var headers = new Headers();
var bearer = "Bearer " + access_token;
headers.append("Authorization", bearer);
var options = {
    method: "GET",
    headers: headers
};

var graphEndpoint = "<https://graph.microsoft.com/v1.0/me>";

fetch(graphEndpoint, options)
    .then(function (response) {
        //do something with response
    });

Prérécupération de jeton pour l’authentification d’application imbriquée (NAA)

Pour améliorer les performances et réduire la latence d’authentification, l’authentification d’application imbriquée (NAA) prend en charge la prérécupération des jetons. Cette fonctionnalité permet à l’hôte d’acquérir de manière proactive des jetons d’authentification avant le lancement de l’application, ce qui permet un accès plus rapide aux ressources protégées.

Guide pratique pour activer la prérécupération des jetons

Pour activer la prérécupération de jeton, mettez à jour votre manifeste d’application Teams vers la version 1.22 ou ultérieure et incluez la nestedAppAuthInfo section dans webApplicationInfo.

{
 "webApplicationInfo": {
   "id": "33333ddd-0000-0000-0000-88888757bbbb",
   "resource": "api://app.com/botid-33333ddd-0000-0000-0000-88888757bbbb",
   "nestedAppAuthInfo": [
     {
       "redirectUri": "brk-multihub://app.com",
       "scopes": ["openid", "profile", "offline_access"],
       "claims": "{\"access_token\":{\"xms_cc\":{\"values\":[\"CP1\"]}}}"
     }
   ]
 }
}

Mode de fonctionnement

Lorsque la prérécupération de jeton est activée, l’environnement hôte tente d’acquérir et de mettre en cache les jetons requis avant le rendu de l’application. Ces jetons sont stockés en mémoire et mis à la disposition de l’application dès le lancement.

Ce comportement est similaire à la fonctionnalité de prérécupération dans le modèle d’authentification unique Teams hérité, où l’API getAuthToken a été automatiquement déclenchée lors du chargement de la tabulation. Avec l’authentification d’application imbriquée (NAA), cette fonctionnalité est introduite par le biais de la configuration du manifeste, ce qui améliore les performances sans nécessiter d’échange de jetons back-end.

Avantages de la prérécupération de jeton dans NAA

• Améliorer les performances en réduisant les délais d’authentification au démarrage de l’application
• Activer l’authentification unique (SSO) entre les applications imbriquées sans connexions répétées

Meilleures pratiques

• Utilisez l’authentification sans assistance 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 dans le stockage du navigateur. Si elle n’en trouve pas, la bibliothèque effectue une demande silencieuse pour Microsoft Entra ID et s’il existe une session utilisateur active (déterminée par un cookie défini dans le navigateur sur le domaine Microsoft Entra), Microsoft Entra’ID retourne un nouveau jeton. La bibliothèque n’appelle pas automatiquement la acquireTokenSilent méthode . Nous vous recommandons d’appeler acquireTokenSilent dans votre application avant d’effectuer un appel d’API pour obtenir un jeton valide.

  Dans certains cas, la tentative d’obtention du jeton à l’aide de la acquireTokenSilent méthode échoue. Par exemple, lorsqu’une session utilisateur a expiré avec un ID de Microsoft Entra ou une modification de mot de passe par l’utilisateur de l’application, acquireTokenSilent échoue. Appelez la méthode interactive acquire token (acquireTokenPopup).

• Disposez d’un secours : les flux NAA offrent la compatibilité dans l’écosystème Microsoft. Toutefois, votre application peut apparaître dans des clients de bas niveau ou hérités qui ne sont pas mis à jour pour prendre en charge NAA. Dans ce cas, votre application ne peut pas prendre en charge l’authentification unique transparente, et vous devrez peut-être appeler des API spéciales pour interagir avec l’utilisateur afin d’ouvrir des boîtes de dialogue d’authentification. Pour plus d’informations, consultez Activer l’authentification unique pour l’application d’onglet.

  Remarque

  Vous ne devez pas utiliser NAA si vous utilisez un fournisseur d’identité non Microsoft Entra. Vous pouvez utiliser l’authentification contextuelle à la place.

• Prise en charge de NAA : NAA peut ne pas être pris en charge dans tous les environnements d’application hôte. Pour vérifier si le client actuel prend en charge cette fonctionnalité, vous pouvez appeler l’API spécifiée pour déterminer son status. Une valeur de retour indique la prise en charge de true NAA, alors qu’elle false suggère qu’elle n’est pas prise en charge.

• Tester votre application dans plusieurs environnements : si votre application est censée fonctionner dans les déploiements d’affichage web et de navigateur, nous vous recommandons de tester votre application dans les deux environnements de déploiement pour vous assurer qu’elle se comporte comme prévu. Certaines API qui fonctionnent dans le navigateur peuvent ne pas fonctionner dans les affichages web.

Exemple de code

Voir aussi

• Plateforme d’identités Microsoft et flux OAuth 2.0 On-Behalf-Of
• Mise en cache dans MSAL
• Présentation de l’authentification d’application imbriquée : protocole d’authentification amélioré pour votre application Teams