Authentification d’application imbriquée

Remarque

L’authentification d’application imbriquée (NAA) est prise en charge uniquement dans les applications monopages (SPA), telles que les onglets.

NAA est un nouveau protocole d’authentification pour les sites web monopage intégrés dans des 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 OBO (On-Behalf-Of) :

  • NAA exige que vous utilisiez uniquement la bibliothèque MSAL.js. Vous n’avez pas besoin d’utiliser la fonction dans la getAuthToken bibliothèque cliente JavaScript de 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 de faire appel à 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 souligne la différence entre Teams Microsoft Entra l’authentification unique et NAA :

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

  • L’administrateur informatique peut bloquer l’application ou accorder uniquement certaines autorisations 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’utilisation de l’ANA

Scénario Description
Consentement à l’authentification unique (et autres autorisations) Tom, un nouveau membre de l’équipe de conception de Contoso, doit utiliser l’application Contoso dans les réunions Teams pour collaborer sur des tableaux blancs. Lors de la première utilisation, une boîte de dialogue invite Tom à accorder des autorisations, notamment la lecture de son profil pour son avatar (User.Read). Une fois son consentement donné, Tom pourra utiliser Contoso en toute transparence lors de futures réunions sur tous les appareils.
Nouvelle authentification ou accès conditionnel, authentification renforcée Jean, lorsqu’il travaille depuis l’Australie, rencontre un déclencheur d’accès conditionnel nécessitant une authentification multifacteur (MFA) pour accéder à Contoso dans Teams. Une boîte de dialogue informe Tom qu’une vérification supplémentaire est nécessaire, ce qui les guide tout au long du processus MFA pour continuer à utiliser Contoso.
Erreurs Tom fait face à une erreur de connexion avec Contoso en raison d’un problème de récupération des informations de compte. Tom rencontre un bouton de nouvelle tentative qui l’invite à se réauthentifier. Cependant, ils découvrent que l’administrateur système a restreint l’accès à Contoso.

Configurer NAA

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

  1. Inscrire votre SPA
  2. Ajouter des courtiers 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 Microsoft Entra ID pour votre complément sur le 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, le 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à du NAA et de l’authentification unique (SSO), consultez Enregistrer votre application monopage.

Ajouter des courtiers approuvés

Pour configurer l’authentification des applications imbriquées, votre application doit configurer activement un URI de redirection pour votre application. L’URI de redirection indique à la Plateforme d’identités Microsoft que votre application peut être négociée par les 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 sur lesquels il est configuré pour s’exécuter, 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, consultez Étendre les applications Teams à Microsoft 365.

Initialiser l’application cliente publique

Remarque

Pour garantir la réussite de l’authentification, initialisez TeamsJS avant d’initialiser MSAL.

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 des utilisateurs. Il tente d’obtenir un jeton d’accès en mode silencieux. En cas d’échec, l’utilisateur est invité à donner son consentement. Le jeton est ensuite utilisé pour appeler l’API Microsoft Graph ou d’autres ressources protégées par Microsoft Entra ID. Contrairement au flux OBO, vous n’avez pas besoin d’autoriser au préalable vos hôtes à 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 getActiveAccount l’API 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 silencieusement sans interaction de l’utilisateur. accessTokenRequest Spécifie les étendues pour lesquelles le jeton d’accès est demandé. L’ANA prend en charge le consentement progressif et dynamique. Veillez à toujours demander les étendues minimales nécessaires à l’exécution de votre code pour accomplir 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 que vous avez reçu le jeton, utilisez-le pour appeler l’API. Cela garantit que l’API est appelée avec un jeton valide pour effectuer des demandes authentifiées au serveur.

L’exemple suivant montre comment effectuer une demande authentifiée à l’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électure de jetons 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électure de 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.

Procédure pour activer la prélecture de jetons

Pour activer la prélecture de jetons, mettez à jour le manifeste de votre application Teams vers la version 1.22 ou ultérieure et incluez la section dans webApplicationInfo.nestedAppAuthInfo

{
 "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\"]}}}"
     }
   ]
 }
}

Importante

  • Pour chaque demande de prérécupération de jetons NAA, spécifiez l’ID client d’enregistrement Microsoft Entra ID de l’agent ou de l’application dans le champ facultatif clientId de l’entrée correspondantenestedAppAuthInfo. Lorsqu’elle est fournie, cette valeur est utilisée pour prérécupérer le jeton pour cette entrée. Si une entrée n’inclut clientIdpas , l’hôte utilise webApplicationInfo.id comme ID client pour la demande de prérécupération de jeton NAA de cette entrée.
  • webApplicationInfo.id est l’ID client de secours pour les entrées qui ne spécifient pas clientId. Il n’est pas nécessaire qu’il corresponde à tous les clientId d’entrée de gamme. Si une application utilise uniquement webApplicationInfo.id pour la prélecture de jetons NAA, cette valeur doit correspondre à l’ID client de l’inscription Microsoft Entra ID de l’application utilisée pour ses demandes de jetons NAA réelles.
  • Les valeurs et tous les champs à webApplicationInfo.id l’intérieur nestedAppAuthInfo doivent correspondre exactement aux paramètres utilisés dans la demande de jeton NAA d’exécution de l’application. Toute incompatibilité, telle que des différences dans les étendues, les URI de redirection ou les revendications, empêche l’hôte de servir le jeton à partir du cache.
  • Les jetons préchargés sont stockés en mémoire pendant une courte durée et sont destinés à être utilisés uniquement lors du chargement initial de l’application. Si l’application tente de récupérer un jeton ultérieurement, par exemple en réponse à une action d’un utilisateur, le jeton prérécupéré peut ne plus être disponible. Dans ce cas, l’application doit lancer une nouvelle demande de jeton à l’aide de flux d’authentification standard.

Mode de fonctionnement

Lorsque la prélecture des jetons est activée, l’environnement hôte tente d’acquérir et de mettre en cache les jetons requis avant que l’application ne soit rendue. Ces jetons sont stockés en mémoire et mis à la disposition de l’application immédiatement après le lancement.

Ce comportement est similaire à la fonctionnalité de prérécupération dans le modèle SSO Teams hérité, où l’API était automatiquement déclenchée pendant le chargement de l’onglet getAuthToken . 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électure des jetons 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) sur les applications imbriquées sans connexions répétées

Remarque

La prélecture des jetons est actuellement prise en charge uniquement dans les clients web et de bureau Microsoft Teams.

Meilleures pratiques

  • Utilisez 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 jetons silencieuses sans inviter 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 envoie une demande silencieuse à 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 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’il y a une session utilisateur expirée avec Microsoft Entra ID ou un changement de mot de passe par l’utilisateur de l’application, acquireTokenSilent échoue. Appelez la méthode de jeton d’acquisition interactive (acquireTokenPopup).

  • Avoir une solution de repli : les flux NAA offrent une compatibilité dans tout l’écosystème Microsoft. Toutefois, votre application peut apparaître dans les clients de niveau inférieur ou hérités qui ne sont pas mis à jour pour prendre en charge NAA. Dans de tels 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 les 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 n’est peut-être pas pris en charge dans tous les environnements d’applications hôtes. Pour vérifier si le client actuel prend en charge cette fonctionnalité, vous pouvez appeler l’API spécifiée pour déterminer son état. Une valeur de retour de true indique la prise en charge de NAA, tandis false qu’elle suggère qu’elle n’est pas prise en charge.

  • Testez 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 vues web.

Exemple de code

Exemple de nom Description .NET Node.js
Authentification d’application imbriquée Cet échantillon présente l’authentification unique (SSO) de Microsoft Entra dans un onglet Microsoft Teams, à l’aide du flux OBO (On-Behalf-Of) pour appeler l’API Graph Microsoft au nom de l’utilisateur. View View

Voir aussi

  • Dernière mise à jour :