Comptes dans le navigateur MSAL

Il s’agit de la documentation comptes spécifiques à la plateforme pour la @azure/msal-browser bibliothèque, qui fournit les API suivantes pour accéder aux comptes mis en cache :

  • getAllAccounts(): retourne tous les comptes actuellement dans le cache. Prend en charge un filtre facultatif pour retourner un ensemble spécifique de comptes. Une application doit choisir un compte pour acquérir des jetons en mode silencieux.
  • getAccount(): retourne le premier compte mis en cache qui correspond au filtre passé. L’ordre dans lequel les comptes sont lus à partir du cache est arbitraire et il n’existe aucune garantie que le premier compte de la liste filtrée sera le même pour les deux appels de getAccount. Comme expliqué ci-dessous, l’augmentation du nombre d’attributs de filtre fournit des correspondances plus exactes.

Account Filter, objet

La documentation de type AccountFilter répertorie les propriétés qui peuvent être utilisées et combinées pour filtrer les comptes.

Note

Un seul attribut de filtre de compte n’est généralement pas garanti pour identifier de manière unique un objet de compte mis en cache. L’ajout d’une combinaison d’attributs qui ne se répètent pas ensemble, par homeAccountId + localAccountIdexemple, peut aider à affiner la recherche.

Note

realm se trouve tenantId dans le cache.

Les API suivantes getAccountBy ont été déconseillées. getAccount() Utilisez plutôt un objet de filtre approprié :

  • getAccountByHomeId(): utilisez getAccount({ homeAccountId }) à la place.
  • getAccountByLocalId(): utilisez getAccount({ localAccountId }) à la place.
  • getAccountByUsername(): utilisez getAccount({ username }) à la place.

Voici des exemples d’utilisation qui couvrent ces API :


let homeAccountId = null; // Initialize global accountId (can also be localAccountId or username) used for account lookup later, ideally stored in app state

// This callback is passed into `acquireTokenPopup` and `acquireTokenRedirect` to handle the interactive auth response
function handleResponse(resp) {
    if (resp !== null) {
        homeAccountId = resp.account.homeAccountId; // alternatively: resp.account.homeAccountId or resp.account.username
    } else {
        const currentAccounts = myMSALObj.getAllAccounts();
        if (currentAccounts.length < 1) { // No cached accounts
            return;
        } else if (currentAccounts.length > 1) { // Multiple account scenario
            // Add account selection code here
            homeAccountId = ...
        } else if (currentAccounts.length === 1) {
            homeAccountId = currentAccounts[0].homeAccountId; // Single account scenario
        }
    }
}

À présent, les propriétés de compte telles que : homeAccountId, localAccountIdet username peuvent être utilisées pour rechercher le compte mis en cache avant d’acquérir un jeton en mode silencieux :

// This method attempts silent token acquisition and falls back on acquireTokenPopup
async function getTokenPopup(request, homeAccountId) {
    // In this case, accounts are filtered by homeAccountId, but more attributes can be added to refine the search and increase the precision of the account filter
    const accountFilter = {
        homeAccountId: homeAccountId,
    };
    request.account = myMSALObj.getAccount(accountFilter);
    return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
        // Handle error
        return await myMSALObj.acquireTokenPopup(request);
    });
}

Filtrage par indicateur de connexion

À compter de @azure/msal-browser@3.2.0, toutes les valeurs d’indicateur de connexion peuvent être utilisées pour rechercher et filtrer des comptes. Pour filtrer par indicateur de connexion, MSAL compare la loginHint valeur de l’objet AccountFilter aux attributs de compte suivants (par ordre de priorité) pour rechercher des correspondances :

  • login_hint Revendication de jeton d’ID
  • username propriété account
  • upn Revendication de jeton d’ID

Note

Tous les attributs ci-dessus peuvent être passés dans le filtre de compte en tant que loginHint propriété. Le filtre de compte accepte également l’attribut username comme username, et génère une recherche plus performante.

Utilisation de login_hint la revendication

const accountFilter = {
    loginHint: previouslyObtainedIdTokenClaims.login_hint;
};
request.account = myMSALObj.getAccount(accountFilter);
return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
    // Handle error
    return await myMSALObj.acquireTokenPopup(request);
});

Utilisation de « nom d’utilisateur »

Note

La username valeur peut être incluse dans l’objet AccountFilter en tant que ou usernameloginHint. Cela est dû au fait que la username revendication est l’une des 3 valeurs (ainsi que les revendications de login_hintupn jeton d’ID) que le service de jeton accepte comme indicateur de connexion. Si votre application est certaine que la valeur en question est une usernamevaleur, la définition de la AccountFilter.username propriété génère de meilleures performances de recherche. En étant en mesure de définir une username valeur comme loginHint étant utile si votre application utilise un indicateur de connexion et ne conserve pas le contexte si cette valeur provient d’une revendication ou login_hintupn d’une usernamerevendication.

Passage username en tant que loginHint

const accountUsername = userProfile.username;
const accountFilter = {
    loginHint: accountUsername;
};
request.account = myMSALObj.getAccount(accountFilter);
return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
    // Handle error
    return await myMSALObj.acquireTokenPopup(request);
});

Passage username en tant que username

const accountUsername = userProfile.username;
const accountFilter = {
    username: accountUsername;
};
request.account = myMSALObj.getAccount(accountFilter);
return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
    // Handle error
    return await myMSALObj.acquireTokenPopup(request);
});

Utilisation de upn la revendication

const accountFilter = {
    loginHint: previouslyObtainedIdTokenClaims.upn;
};
request.account = myMSALObj.getAccount(accountFilter);
return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
    // Handle error
    return await myMSALObj.acquireTokenPopup(request);
});

API de compte actif

La @azure/msal-browser bibliothèque fournit également 2 API pratiques pour vous aider à suivre quel compte est actuellement « actif » et doit être utilisé pour les demandes de jetons.

  • getActiveAccount(): retourne le compte actif actif
  • setActiveAccount(): reçoit un objet de compte et le définit comme compte actif

Choisir le compte à utiliser pour acquérir des jetons dépend de l’application. Toutefois, une fois que vous avez déterminé le compte que vous souhaitez utiliser, appelez simplement l’API setActiveAccount() avec l’objet de compte choisi. Tous acquireTokenles appels ssoSilentlogin utilisent désormais le compte actif par défaut si un autre compte n’est pas spécifié dans la demande individuelle. Pour effacer le compte actif que vous pouvez appeler setActiveAccount(null).

function login() {
    return myMsalObj.loginPopup().then((response) => {
        // After a successful login set the active account to be the user that just logged in
        myMsalObj.setActiveAccount(response.account);
    });
}

function getAccessToken() {
    // Providing an account in the token request is not required if there is an active account set
    return myMsalObj.acquireTokenSilent({ scopes: ["User.Read"] });
}

Remarque : À partir de la version 2.16.0, le compte actif est stocké dans l’emplacement du cache configuré sur votre PublicClientApplication instance. Si vous utilisez une version précédente, le compte actif est stocké en mémoire et doit donc être réinitialisé sur chaque chargement de page.

Authentification d’application imbriquée

Pour les applications NAA et setActiveAccount()getActiveAccount() sont NO-OP API. Bien que les utilisateurs puissent définir et obtenir des comptes actifs, ils sont activement ignorés, car l’application NAA est toujours censée avoir un compte et le compte est fourni par l’application hôte avec accountContext. À l’avenir, lorsque plusieurs comptes sont pris en charge sur les hubs, ce comportement devrait changer.

Remarques

  • L’exemple msal-browser par défaut actuel comporte un scénario de compte unique opérationnel.
  • Si vous avez plusieurs scénarios de comptes, modifiez l’exemple (en handleResponse()) pour répertorier tous les comptes mis en cache et choisissez un compte spécifique.
  • Si une application souhaite récupérer un compte en fonction du username, elle doit enregistrer le username (à partir de la réponse d’une login API pour un utilisateur spécifique) avant d’utiliser le username filtre dans l’API getAccount() .
  • getAllAccounts() retourne plusieurs comptes si vous avez effectué plusieurs demandes de jetons interactifs et que l’utilisateur a sélectionné des comptes différents dans deux ou plusieurs de ces interactions. Vous devrez peut-être transmettre prompt: "select_account" ou prompt: "login" à l’API d’acquisition interactive ou de connexion pour Microsoft Entra ID d’afficher l’écran de sélection du compte après la première interaction.
  • Les API de compte retournent l’état du compte local et ne reflètent pas nécessairement l’état du serveur. Ils retournent des comptes qui se sont précédemment connectés à cette application à l’aide de MSAL.js et la session de serveur peut ou ne pas toujours être active.
  • Deux applications hébergées sur différents domaines ne partagent pas l’état du compte en raison du stockage du navigateur en cours de ségement par domaine.
  • getAllAccounts() n’est pas ordonné et n’est pas garanti d’être dans le même ordre entre plusieurs appels
  • Chaque appel réussi à une API acquireToken ou login retourne exactement un compte
  • Last updated on