Initialiser des applications clientes avec MSAL.js

Article
02/27/2024

Cet article décrit l’initialisation de la Bibliothèque d’authentification Microsoft pour JavaScript (MSAL.js) avec une instance d’application d’agent utilisateur.

L’application agent utilisateur est une forme d'application cliente publique dans laquelle le code client est exécuté dans un agent utilisateur, par exemple un navigateur web. Ce type de clients ne stocke pas de clés secrètes car le contexte du navigateur est directement accessible.

Pour plus d’informations sur les types d’application cliente et les options de configuration des applications, consultez Applications clientes publiques et confidentielles dans MSAL.

Prérequis

Avant d’initialiser une application, vous devez d’abord l’inscrire dans le Centre d’administration Microsoft Entra, en établissant une relation d’approbation entre votre application et la plateforme d’identités Microsoft.

Une fois l’application inscrite, vous avez besoin d’une partie ou de toutes les valeurs suivantes qui se trouvent dans le Centre d’administration Microsoft Entra.

Valeur	Obligatoire	Description
ID d’application (client)	Obligatoire	GUID qui identifie de manière unique votre application dans la plateforme d’identités Microsoft.
Authority	Facultatif	URL du fournisseur d’identité (instance) et audience de connexion de votre application. L’instance et l’audience de connexion, une fois concaténées, constituent l’autorité.
ID de l’annuaire (locataire)	Facultatif	Spécifiez l’ID Répertoire (locataire) si vous générez une application métier seulement pour votre organisation, souvent appelée application monolocataire.
URI de redirection	Facultatif	Si vous générez une application web, `redirectUri` spécifie l’emplacement où le fournisseur d’identité (la plateforme d’identités Microsoft) doit retourner les jetons de sécurité émis.

Initialiser des applications MSAL.js 2.x

Initialisez le contexte d’authentification MSAL.js en instanciant un PublicClientApplication avec un objet Configuration. La propriété de configuration minimale nécessaire est le clientID de l’application. Elle est affichée sous la forme ID d’application (client) dans la page Vue d’ensemble de l’inscription de l’application du Centre d’administration Microsoft Entra.

Voici un exemple d’objet de configuration et d’instanciation de PublicClientApplication :

const msalConfig = {
  auth: {
    clientId: "Enter_the_Application_Id_Here",
    authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here",
    knownAuthorities: [],
    redirectUri: "https://localhost:{port}/redirect",
    postLogoutRedirectUri: "https://localhost:{port}/redirect",
    navigateToLoginRequestUrl: true,
  },
  cache: {
    cacheLocation: "sessionStorage",
    storeAuthStateInCookie: false,
  },
  system: {
    loggerOptions: {
      loggerCallback: (
        level: LogLevel,
        message: string,
        containsPii: boolean
      ): void => {
        if (containsPii) {
          return;
        }
        switch (level) {
          case LogLevel.Error:
            console.error(message);
            return;
          case LogLevel.Info:
            console.info(message);
            return;
          case LogLevel.Verbose:
            console.debug(message);
            return;
          case LogLevel.Warning:
            console.warn(message);
            return;
        }
      },
      piiLoggingEnabled: false,
    },
    windowHashTimeout: 60000,
    iframeHashTimeout: 6000,
    loadFrameTimeout: 0,
  },
};

// Create an instance of PublicClientApplication
const msalInstance = new PublicClientApplication(msalConfig);

// Handle the redirect flows
msalInstance
  .handleRedirectPromise()
  .then((tokenResponse) => {
    // Handle redirect response
  })
  .catch((error) => {
    // Handle redirect error
  });

`handleRedirectPromise`

Appelez handleRedirectPromise quand l’application utilise les flux de redirection. Durant l’utilisation des flux de redirection, handleRedirectPromise doit être exécuté à chaque chargement de page.

Trois résultats sont possibles à partir de la promesse :

.then est appelé et tokenResponse est vrai : L’application est retournée à partir d’une opération de redirection réussie.
.then est appelé et tokenResponse est faux (null) : L’application n’est pas retournée à partir d’une opération de redirection.
.catch est appelé : L’application est retournée à partir d’une opération de redirection et une erreur s’est produite.

Initialiser des applications MSAL.js 1.x

Initialisez le contexte d’authentification de MSAL 1.x en instanciant UserAgentApplication avec un objet de configuration. La propriété de configuration minimale nécessaire est le clientID de votre application. Elle est affichée sous la forme ID d’application (client) dans la page Vue d’ensemble de l’inscription de l’application du Centre d’administration Microsoft Entra.

Pour les méthodes d'authentification avec des flux de redirection (loginRedirect et acquireTokenRedirect) dans MSAL.js 1.2.x ou version antérieure, vous devez explicitement enregistrer un rappel en cas de réussite ou d'erreur via la méthode handleRedirectCallback(). L’inscription explicite du rappel est nécessaire dans MSAL.js 1.2.x et les versions antérieures, car les flux de redirection ne retournent pas de promesses comme le font les méthodes ayant une expérience utilisateur de fenêtre contextuelle. L’inscription du rappel est facultative dans MSAL.js 1.3.x et les versions ultérieures.

// Configuration object constructed
const msalConfig = {
  auth: {
    clientId: "Enter_the_Application_Id_Here",
  },
};

// Create UserAgentApplication instance
const msalInstance = new UserAgentApplication(msalConfig);

function authCallback(error, response) {
  // Handle redirect response
}

// Register a redirect callback for Success or Error (when using redirect methods)
// **REQUIRED** in MSAL.js 1.2.x and earlier
// **OPTIONAL** in MSAL.js 1.3.x and later
msalInstance.handleRedirectCallback(authCallback);

Instance et configuration uniques

MSAL.js 1.x et 2.x sont tous deux conçus pour avoir une seule instance et une seule configuration de UserAgentApplication ou PublicClientApplication, respectivement, afin de représenter un seul contexte d’authentification.

Il n’est pas recommandé d’utiliser plusieurs instances de UserAgentApplication ou PublicClientApplication, car elles peuvent entraîner des conflits au niveau des entrées du cache et du comportement dans le navigateur.

Étapes suivantes

L’exemple de code MSAL.js 2.x sur GitHub illustre l’instanciation de PublicClientApplication avec un objet Configuration :

Partage via