Contas no MSAL Browser

Esta é a documentação de Contas específica da plataforma para a @azure/msal-browser biblioteca, que fornece as seguintes APIs para aceder a contas em cache:

• getAllAccounts(): devolve todas as contas atualmente na cache. Suporta um filtro opcional para devolver um conjunto específico de contas. Uma aplicação deve escolher uma conta para adquirir tokens silenciosamente.
• getAccount(): devolve a primeira conta em cache que corresponde ao filtro passado. A ordem em que as contas são lidas da cache é arbitrária e não há garantia de que a primeira conta na lista filtrada seja a mesma para quaisquer duas chamadas de getAccount. Como explicado abaixo, aumentar o número de atributos do filtro fornecerá correspondências mais exatas.

Objeto de Filtro da Conta

A documentação do tipo AccountFilter lista as propriedades que podem ser usadas e combinadas para filtrar contas.

As seguintes getAccountBy APIs foram obsoletas. Por favor, use getAccount() com um objeto de filtro apropriado:

• getAccountByHomeId(): use getAccount({ homeAccountId }) em vez disso.
• getAccountByLocalId(): use getAccount({ localAccountId }) em vez disso.
• getAccountByUsername(): use getAccount({ username }) em vez disso.

Segue-se um exemplo de utilização que cobre estas APIs:

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

Agora, propriedades da conta como: homeAccountId, localAccountId, e username podem ser usadas para consultar a conta em cache antes de adquirir um token silenciosamente:

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

Filtragem por dica de login

A partir de @azure/msal-browser@3.2.0, todos os valores das dicas de login podem ser usados para procurar e filtrar contas. Para filtrar por dica de login, a MSAL irá comparar o loginHint valor no AccountFilter objeto com os seguintes atributos da conta (por ordem de precedência) para procurar correspondências:

• login_hint Reivindicação do token de identificação
• username Propriedade da conta
• upn Reivindicação do token de identificação

Utilização login_hint da reivindicação

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

Usar 'nome de utilizador''

Passando username como 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);
});

Passando username como 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);
});

Utilização upn da reivindicação

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

APIs de Contas Ativas

A @azure/msal-browser biblioteca também disponibiliza 2 APIs convenientes para o ajudar a acompanhar qual conta está atualmente "ativa" e deve ser usada para pedidos de tokens.

• getActiveAccount(): Devolve a conta ativa atual
• setActiveAccount(): Recebe um objeto de conta e define-o como conta ativa

Decidir qual conta usar para adquirir tokens depende da aplicação, no entanto, depois de determinar qual conta pretende usar, basta chamar a setActiveAccount() API com o objeto de conta escolhido. Qualquer acquireToken, login ou ssoSilent chamada passará a usar a conta ativa por defeito se uma conta diferente não for especificada no pedido individual. Para limpar a conta atualmente ativa, pode ligar setActiveAccount(null)para .

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

Nota: A partir da versão 2.16.0, a conta ativa está armazenada na localização de cache configurada na sua PublicClientApplication instância. Se estiver a usar uma versão anterior, a conta ativa é armazenada na memória e, por isso, tem de ser reiniciada a cada carregamento da página.

Autenticação de Aplicações Aninhadas

Para aplicações NAA, setActiveAccount() e getActiveAccount() são NO-OP APIs. Embora os utilizadores possam criar e obter contas ativas, são ativamente ignoradas, pois espera-se que a aplicação NAA tenha sempre uma conta e a conta é fornecida pela aplicação anfitriã com accountContext. No futuro, quando múltiplas contas forem suportadas entre os hubs, espera-se que este comportamento mude.

Notes

• A amostra padrão atual do navegador msal tem um cenário funcional de conta única.
• Se tiver um cenário com múltiplas contas, por favor modifique o exemplo (em handleResponse()) para listar todas as contas em cache e escolha uma conta específica.
• Se uma aplicação quiser recuperar uma conta baseada no username, precisa de guardar o username (da resposta de uma login API para um utilizador específico) antes de usar o username filtro na getAccount() API.
• getAllAccounts() Devolve múltiplas contas se tiver feito vários pedidos interativos de tokens e o utilizador tiver selecionado contas diferentes em duas ou mais dessas interações. Pode ser necessário passar prompt: "select_account" ou prompt: "login" aceder à API interativa acquireToken ou de login para que o Microsoft Entra ID mostre o ecrã de seleção da conta após a primeira interação.
• As APIs da conta devolvem o estado local da conta e não refletem necessariamente o estado do servidor. Eles devolvem contas que já tinham iniciado sessão nesta aplicação usando MSAL.js e a sessão do servidor pode ou não continuar ativa.
• Duas aplicações alojadas em domínios diferentes não partilham o estado da conta devido ao armazenamento do navegador ser segmentado por domínio.
• getAllAccounts() não é ordenado e não é garantido que esteja na mesma ordem em múltiplas chamadas
• Cada chamada bem-sucedida para um acquireToken ou API de login devolverá exatamente uma conta