Konta w przeglądarce MSAL

Jest to dokumentacja kont specyficznych dla platformy dla @azure/msal-browser biblioteki, która udostępnia następujące interfejsy API umożliwiające dostęp do buforowanych kont:

  • getAllAccounts(): zwraca wszystkie konta aktualnie w pamięci podręcznej. Obsługuje opcjonalny filtr, aby zwrócić określony zestaw kont. Aplikacja musi wybrać konto, aby uzyskać tokeny w trybie dyskretnym.
  • getAccount(): zwraca pierwsze buforowane konto zgodne z przekazanym filtrem. Kolejność odczytywania kont z pamięci podręcznej jest dowolna i nie ma gwarancji, że pierwsze konto na filtrowanej liście będzie takie samo dla dwóch wywołań getAccount. Jak wyjaśniono poniżej, zwiększenie liczby atrybutów filtru zapewni dokładniejsze dopasowania.

Obiekt filtru konta

Dokumentacja typu AccountFilter zawiera listę właściwości, których można używać i łączyć w celu filtrowania kont.

Note

Atrybut filtru pojedynczego konta zwykle nie gwarantuje unikatowego identyfikowania obiektu konta w pamięci podręcznej. Dodanie kombinacji atrybutów, które nie powtarzają się razem, takich jak homeAccountId + localAccountId, może pomóc w uściśliniu wyszukiwania.

Note

realm znajduje się tenantId w pamięci podręcznej.

Następujące getAccountBy interfejsy API zostały przestarzałe. Zamiast tego użyj getAccount() odpowiedniego obiektu filtru:

  • getAccountByHomeId(): zamiast tego użyj getAccount({ homeAccountId }).
  • getAccountByLocalId(): zamiast tego użyj getAccount({ localAccountId }).
  • getAccountByUsername(): zamiast tego użyj getAccount({ username }).

Poniżej przedstawiono przykłady użycia, które obejmują następujące interfejsy 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
        }
    }
}

Teraz właściwości konta, takie jak : homeAccountId, localAccountIdi username mogą służyć do wyszukiwania buforowanego konta przed dyskretnym uzyskaniem tokenu:

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

Filtrowanie według wskazówek logowania

Od programu @azure/msal-browser@3.2.0wszystkie wartości wskazówek logowania mogą służyć do wyszukiwania i filtrowania kont. Aby filtrować według wskazówek logowania, biblioteka MSAL porówna loginHint wartość w AccountFilter obiekcie z następującymi atrybutami konta (w kolejności pierwszeństwa), aby wyszukać dopasowania:

  • login_hint Oświadczenie tokenu identyfikatora
  • username właściwość konta
  • upn Oświadczenie tokenu identyfikatora

Note

Wszystkie powyższe atrybuty można przekazać do filtru loginHint konta jako właściwości. Filtr konta będzie również akceptować username atrybut jako username, i zwróci bardziej wydajne wyszukiwanie.

Korzystanie z login_hint oświadczenia

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

Używanie nazwy użytkownika

Note

Wartość username może być uwzględniona w AccountFilter obiekcie jako username lub loginHint. Dzieje się tak, ponieważ username oświadczenie jest jedną z 3 wartości (wraz z oświadczeniami tokenu login_hint identyfikatora i upn ), które usługa tokenu akceptuje jako wskazówkę logowania. Jeśli aplikacja jest pewna, że wartość, o którą mowa, jest wartością username, ustawienie jej jako AccountFilter.username właściwości zapewni lepszą wydajność wyszukiwania. Możliwość ustawienia wartości jako przydatnejusername, jeśli aplikacja korzysta z wskazówki logowania i nie zachowuje kontekstu na temat tego, czy ta wartość pochodzi z username, login_hintlub upn oświadczenia.loginHint

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

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

Korzystanie z upn oświadczenia

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

Interfejsy API aktywnego konta

Biblioteka @azure/msal-browser udostępnia również 2 wygodne interfejsy API, które ułatwiają śledzenie, które konto jest obecnie "aktywne" i powinno być używane na potrzeby żądań tokenów.

  • getActiveAccount(): Zwraca bieżące aktywne konto
  • setActiveAccount(): odbiera obiekt konta i ustawia go jako aktywne konto

Podjęcie decyzji o tym, które konto ma być używane do uzyskiwania tokenów, zależy od aplikacji, jednak po określeniu, którego konta chcesz użyć, po prostu wywołaj setActiveAccount() interfejs API z wybranym obiektem konta. Wszystkie acquireTokenwywołania , login lub ssoSilent będą teraz domyślnie używać aktywnego konta, jeśli inne konto nie zostanie określone w pojedynczym żądaniu. Aby wyczyścić aktualnie aktywne konto, możesz wywołać metodę 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"] });
}

Uwaga: w wersji 2.16.0 aktywne konto jest przechowywane w lokalizacji pamięci podręcznej skonfigurowanej w wystąpieniu PublicClientApplication . Jeśli używasz poprzedniej wersji, aktywne konto jest przechowywane w pamięci i w związku z tym musi zostać zresetowane przy każdym ładowaniu strony.

Uwierzytelnianie zagnieżdżonej aplikacji

W przypadku aplikacji setActiveAccount() NAA i getActiveAccount() są NO-OP interfejsami API. Chociaż użytkownicy mogą ustawiać i uzyskiwać aktywne konta, są aktywnie ignorowani, ponieważ aplikacja NAA zawsze ma jedno konto, a konto jest dostarczane przez aplikację hosta za pomocą accountContextusługi . W przyszłości, gdy wiele kont jest obsługiwanych w centrach, to zachowanie ma ulec zmianie.

Notatki

  • Bieżący przykład domyślny msal-browser ma działający scenariusz pojedynczego konta.
  • Jeśli masz scenariusz z wieloma kontami, zmodyfikuj przykład (w handleResponse()programie ), aby wyświetlić listę wszystkich buforowanych kont i wybrać określone konto.
  • Jeśli aplikacja chce pobrać konto na usernamepodstawie elementu , musi zapisać username (z odpowiedzi login interfejsu API dla określonego użytkownika) przed użyciem filtru username w interfejsie getAccount() API.
  • getAllAccounts() Zwróci wiele kont, jeśli wykonano kilka żądań tokenu interaktywnego, a użytkownik wybrał różne konta w co najmniej dwóch tych interakcjach. Może być konieczne przekazanie lub prompt: "login" przejście prompt: "select_account" do interaktywnego interfejsu API acquireToken lub logowania, aby Microsoft Entra ID wyświetlić ekran wyboru konta po pierwszej interakcji.
  • Interfejsy API konta zwracają stan konta lokalnego i nie muszą odzwierciedlać stanu serwera. Zwracają konta, które wcześniej zalogowały się do tej aplikacji przy użyciu MSAL.js, a sesja serwera może być nadal aktywna.
  • Dwie aplikacje hostowane w różnych domenach nie współużytkują stanu konta, ponieważ magazyn przeglądarki jest segementowany przez domenę.
  • getAllAccounts() nie jest uporządkowany i nie ma gwarancji, że jest w tej samej kolejności w wielu wywołaniach
  • Każde pomyślne wywołanie interfejsu API acquireToken lub logowania zwróci dokładnie jedno konto
  • Last updated on