Учетные записи в браузере MSAL

Это документация по учетным записям для конкретной платформы для библиотеки, которая предоставляет следующие API для @azure/msal-browser доступа к кэшированных учетных записям:

  • getAllAccounts(): возвращает все учетные записи в кэше. Поддерживает необязательный фильтр для возврата определенного набора учетных записей. Приложение должно выбрать учетную запись для автоматического получения маркеров.
  • getAccount(): возвращает первую кэшированную учетную запись, которая соответствует фильтру, переданной в. Порядок чтения учетных записей из кэша является произвольным, и нет никаких гарантий, что первая учетная запись в отфильтрованном списке будет одинаковой для всех двух вызовов getAccount. Как описано ниже, увеличение числа атрибутов фильтра обеспечит более точные совпадения.

Объект фильтра учетной записи

В документации по типу AccountFilter перечислены свойства, которые можно использовать и объединять для фильтрации учетных записей.

Note

Обычно один атрибут фильтра учетной записи не гарантирует уникальное определение кэшированного объекта учетной записи. Добавление сочетания атрибутов, которые не повторялись вместе, например homeAccountId + localAccountId, могут помочь уточнить поиск.

Note

realm находится tenantId в кэше.

Следующие getAccountBy API устарели. Вместо этого используйте getAccount() соответствующий объект фильтра:

  • getAccountByHomeId(): используйте getAccount({ homeAccountId }) вместо этого.
  • getAccountByLocalId(): используйте getAccount({ localAccountId }) вместо этого.
  • getAccountByUsername(): используйте getAccount({ username }) вместо этого.

Ниже приведены примеры использования, охватывающие эти 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
        }
    }
}

Теперь свойства учетной записи, такие как : homeAccountId, localAccountIdи username можно использовать для поиска кэшированных учетных записей перед получением токена автоматически:

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

Фильтрация по подсказке для входа

По состоянию @azure/msal-browser@3.2.0на это все значения подсказки для входа можно использовать для поиска и фильтрации учетных записей. Чтобы отфильтровать по указаниям для входа, MSAL сравнивает loginHint значение в AccountFilter объекте со следующими атрибутами учетной записи (в порядке приоритета) для поиска совпадений:

  • login_hint Утверждение маркера идентификатора
  • username свойство учетной записи
  • upn Утверждение маркера идентификатора

Note

Все указанные выше атрибуты можно передать в фильтр учетной loginHint записи в качестве свойства. Фильтр учетной username записи также принимает атрибут как usernameи будет давать более производительный поиск.

Использование login_hint утверждения

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

Использование имени пользователя

Note

Значение username может включаться в AccountFilter объект как или usernameloginHint. Это связано с тем, что username утверждение является одним из 3 значений (а также login_hintupn утверждений маркера идентификатора), которые служба маркеров принимает в качестве указания для входа. Если ваше приложение уверено, что значение, заданное в вопросе, имеет usernameзначение, то присвойте ему значение, так как AccountFilter.username свойство даст лучшую производительность поиска. Возможность задать username значение, как loginHint полезно, если приложение использует подсказку для входа и не сохраняет контекст по тому, было ли это значение получено из usernameили login_hintupn утверждения.

Передача username как 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);
});

Передача username как 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);
});

Использование upn утверждения

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 активных учетных записей

Библиотека @azure/msal-browser также предоставляет 2 удобных API, которые помогают отслеживать учетную запись, которая в настоящее время является активной и должна использоваться для запросов маркеров.

  • getActiveAccount(): возвращает текущую активную учетную запись.
  • setActiveAccount(): получает объект учетной записи и задает его в качестве активной учетной записи.

Выбор учетной записи, используемой для получения маркеров, зависит от приложения, однако после определения учетной записи, которую вы хотите использовать, просто вызовите setActiveAccount() API с выбранным объектом учетной записи. login ssoSilent Любые acquireTokenвызовы теперь будут использовать активную учетную запись по умолчанию, если другая учетная запись не указана в отдельном запросе. Чтобы очистить текущую активную учетную запись, можно вызвать 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"] });
}

Примечание. По состоянию на версию 2.16.0 активная учетная запись хранится в расположении кэша, настроенном в вашем PublicClientApplication экземпляре. Если вы используете предыдущую версию, активная учетная запись хранится в памяти, поэтому ее необходимо сбросить на каждую загрузку страницы.

Вложенная проверка подлинности приложений

Для приложений setActiveAccount() NAA и getActiveAccount() NO-OP API. Хотя пользователи могут задавать и получать активные учетные записи, они активно игнорируются, так как приложение NAA всегда должно иметь одну учетную запись и учетную запись предоставляется ведущим приложением accountContext. В будущем, когда несколько учетных записей поддерживаются в центрах, это поведение, как ожидается, изменится.

Notes

  • Текущий пример msal-browser по умолчанию имеет рабочий сценарий одной учетной записи.
  • Если у вас есть несколько учетных записей, измените пример (in handleResponse()), чтобы вывести список всех кэшированных учетных записей и выбрать определенную учетную запись.
  • Если приложение хочет получить учетную запись на usernameоснове этой учетной записи, необходимо сохранить username (из ответа API для конкретного login пользователя) перед использованием username фильтра в getAccount() API.
  • getAllAccounts() возвращает несколько учетных записей, если вы выполнили несколько интерактивных запросов маркеров, и пользователь выбрал разные учетные записи в двух или более этих взаимодействиях. Чтобы Microsoft Entra ID отобразить экран выбора учетной записи после первого взаимодействия, может потребоваться передать prompt: "select_account" или prompt: "login" в API интерактивного приобретения или входа.
  • API учетной записи возвращают состояние локальной учетной записи и не обязательно отражают состояние сервера. Они возвращают учетные записи, которые ранее вошли в это приложение с помощью MSAL.js, а сеанс сервера может или не был активным.
  • Два приложения, размещенные в разных доменах, не совместно используют состояние учетной записи из-за того, что хранилище браузера выполняется по домену.
  • getAllAccounts() не упорядочен и не гарантируется, что он находится в одном порядке в нескольких вызовах.
  • Каждый успешный вызов к API приобретенияToken или имени входа возвращает ровно одну учетную запись.
  • Last updated on