Účty v prohlížeči MSAL

Toto je dokumentace k účtům pro konkrétní platformu pro knihovnu @azure/msal-browser , která poskytuje následující rozhraní API pro přístup k účtům uloženým v mezipaměti:

  • getAllAccounts(): Vrátí všechny účty, které jsou aktuálně v mezipaměti. Podporuje volitelný filtr pro vrácení konkrétní sady účtů. Aplikace musí zvolit účet pro získání tokenů bezobslužně.
  • getAccount(): Vrátí první účet uložený v mezipaměti, který odpovídá předanému filtru. Pořadí čtení účtů z mezipaměti je libovolné a není zaručeno, že první účet ve filtrovaném seznamu bude stejný pro každé dvě volání getAccount. Jak je vysvětleno níže, zvýšení počtu atributů filtru bude poskytovat přesnější shody.

Objekt filtru účtu

Dokumentace k typu AccountFilter uvádí vlastnosti, které lze použít a zkombinovat k filtrování účtů.

Note

Atribut filtru jednoho účtu obvykle není zaručen, že jednoznačně identifikuje objekt účtu uložený v mezipaměti. Přidání kombinace atributů, které se neopakují dohromady, například homeAccountId + localAccountIdmůže pomoct upřesnit hledání.

Note

realm je tenantId v mezipaměti.

Následující getAccountBy rozhraní API jsou zastaralá. Použijte getAccount() místo toho příslušný objekt filtru:

  • getAccountByHomeId(): použijte getAccount({ homeAccountId }) místo toho.
  • getAccountByLocalId(): použijte getAccount({ localAccountId }) místo toho.
  • getAccountByUsername(): použijte getAccount({ username }) místo toho.

Následuje příklad použití, který se zabývá těmito rozhraními 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
        }
    }
}

Vlastnosti účtu, například: homeAccountId, localAccountIda username lze je použít k vyhledání účtu uloženého v mezipaměti před získáním tokenu bezobslužně:

// 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);
    });
}

Filtrování podle nápovědy pro přihlášení

Od tohoto dne @azure/msal-browser@3.2.0lze všechny hodnoty nápovědy pro přihlášení použít k vyhledání a filtrování účtů. Aby bylo možné filtrovat podle nápovědy pro přihlášení, MSAL porovná loginHint hodnotu v objektu AccountFilter s následujícími atributy účtu (v pořadí podle priority) a vyhledá shody:

  • login_hint Deklarace identity tokenu ID
  • username account property
  • upn Deklarace identity tokenu ID

Note

Všechny výše uvedené atributy lze předat do filtru účtu jako loginHint vlastnost. Filtr účtu také přijme username atribut jako usernamea poskytne výkonnější vyhledávání.

Použití login_hint deklarace identity

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);
});

Použití uživatelského jména

Note

Hodnota username může být zahrnuta v objektu AccountFilter jako buď username nebo loginHint. Důvodem je to, že username deklarace identity je jednou ze 3 hodnot (spolu s deklaracemi tokenů login_hintupn ID), které služba tokenu přijímá jako nápovědu pro přihlášení. Pokud je vaše aplikace jistá, že daná hodnota je , usernamenastavení, protože AccountFilter.username vlastnost bude poskytovat lepší výkon hledání. Schopnost nastavit username hodnotu tak, jak loginHint je užitečná, pokud vaše aplikace využívá nápovědu pro přihlášení a neudržuje kontext, zda tato hodnota pochází z objektu username, login_hintnebo upn deklarace identity.

Předání username jako 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);
});

Předání username jako 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);
});

Použití upn deklarace identity

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);
});

Rozhraní API aktivního účtu

Knihovna @azure/msal-browser také poskytuje 2 praktická rozhraní API, která vám pomůžou sledovat, který účet je aktuálně "aktivní" a měl by se používat pro žádosti o tokeny.

  • getActiveAccount(): Vrátí aktuální aktivní účet.
  • setActiveAccount(): Přijme objekt účtu a nastaví ho jako aktivní účet.

Rozhodnutí o tom, který účet použít k získání tokenů, je však závislý na aplikaci, jakmile ale určíte, který účet chcete použít, jednoduše volejte setActiveAccount() rozhraní API s vybraným objektem účtu. Jakékoli acquireTokenvolání login nebo ssoSilent volání teď budou ve výchozím nastavení používat aktivní účet, pokud není v individuální žádosti zadán jiný účet. Pokud chcete vymazat aktuálně aktivní účet, můžete volat 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"] });
}

Poznámka: Od verze 2.16.0 je aktivní účet uložen v umístění mezipaměti nakonfigurované ve vaší PublicClientApplication instanci. Pokud používáte předchozí verzi, je aktivní účet uložen v paměti, a proto musí být resetována při každém načtení stránky.

Ověřování vnořených aplikací

Pro aplikace setActiveAccount() NAA a getActiveAccount() jsou NO-OP rozhraní API. I když uživatelé mohou nastavit a získat aktivní účty, jsou aktivně ignorovány, protože aplikace NAA je vždy očekává, že jeden účet a účet je poskytován hostitelskou aplikací s accountContext. V budoucnu, kdy se v rámci center podporuje více účtů, se očekává, že se toto chování změní.

Notes

  • Aktuální výchozí ukázka msal-browseru má funkční scénář s jedním účtem.
  • Pokud máte scénář s více účty, upravte ukázku (v) tak, aby se vypsaly všechny účty uložené v handleResponse()mezipaměti a zvolily konkrétní účet.
  • Pokud aplikace chce načíst účet založený na objektu username, musí před použitím username filtru v getAccount() rozhraní API uložit username (z odpovědi login rozhraní API pro konkrétního uživatele).
  • getAllAccounts() vrátí více účtů, pokud jste provedli několik interaktivních žádostí o token a uživatel vybral ve dvou nebo více těchto interakcích různé účty. Možná budete muset předat prompt: "select_account" nebo prompt: "login" do interaktivního rozhraní API pro získání Nebo přihlášení, aby Microsoft Entra ID zobrazit obrazovku výběru účtu po první interakci.
  • Rozhraní API účtu vrací stav místního účtu a nemusí nutně odrážet stav serveru. Vrátí účty, které se dříve přihlásily k této aplikaci pomocí MSAL.js a relace serveru může nebo nemusí být stále aktivní.
  • Dvě aplikace hostované v různých doménách nesdílejí stav účtu kvůli tomu, že úložiště prohlížeče se zachytává podle domény.
  • getAllAccounts() není objednána a není zaručeno, že je ve stejném pořadí napříč více voláními.
  • Každé úspěšné volání rozhraní API pro získání Nebo přihlášení vrátí přesně jeden účet.
  • Last updated on