Contas no Navegador MSAL

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

• getAllAccounts(): retorna todas as contas atualmente no cache. Dá suporte a um filtro opcional para retornar um conjunto específico de contas. Um aplicativo deve escolher uma conta para adquirir tokens silenciosamente.
• getAccount(): retorna a primeira conta armazenada em cache que corresponde ao filtro passado. A ordem na qual as contas são lidas do cache é arbitrária e não há garantia de que a primeira conta na lista filtrada será a mesma para duas chamadas de getAccount. Conforme explicado abaixo, aumentar o número de atributos de filtro fornecerá correspondências mais exatas.

Objeto de filtro de conta

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

As APIs getAccountBy a seguir foram preteridas. Em vez disso, 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.

Veja a seguir um exemplo de uso que abrange 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, as propriedades da conta, como: homeAccountId, localAccountIde username podem ser usadas para pesquisar a conta armazenada 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 logon

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

• login_hint Declaração de token de ID
• username propriedade account
• upn Declaração de token de ID

Usando login_hint declaraçã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);
});

Usando 'username''

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

Usando upn declaraçã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 conta ativa

A @azure/msal-browser biblioteca também fornece 2 APIs convenientes para ajudá-lo a acompanhar qual conta está atualmente "ativa" e deve ser usada para solicitações de token.

• getActiveAccount(): retorna a conta ativa atual
• setActiveAccount(): recebe um objeto de conta e o define como a conta ativa

Decidir qual conta usar para adquirir tokens depende do aplicativo, no entanto, depois de determinar qual conta você deseja usar, basta chamar a setActiveAccount() API com o objeto de conta escolhido. Qualquer acquireTokenou loginssoSilent chamadas usarão a conta ativa por padrão se uma conta diferente não for especificada na solicitação individual. Para limpar a conta ativa no momento, você pode chamar 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"] });
}

Observação: a partir da versão 2.16.0, a conta ativa é armazenada no local do cache configurado em sua PublicClientApplication instância. Se você estiver usando uma versão anterior, a conta ativa será armazenada na memória e, portanto, deverá ser redefinida em cada carga de página.

Autenticação de Aplicativo Aninhada

Para aplicativos NAA e setActiveAccount()getActiveAccount() NO-OP APIs. Embora os usuários possam definir e obter contas ativas, eles são ativamente ignorados, pois o aplicativo NAA sempre deve ter uma conta e a conta é fornecida pelo aplicativo host com accountContext. No futuro, quando várias contas tiverem suporte nos hubs, esse comportamento deverá mudar.

Observações

• O exemplo padrão atual do msal-browser tem um cenário de conta única funcionando.
• Se você tiver um cenário de várias contas, modifique o exemplo (in) para listar todas as contas armazenadas em handleResponse()cache e escolher uma conta específica.
• Se um aplicativo quiser recuperar uma conta com base na username, ele precisará salvar a username (da resposta de uma login API para um usuário específico) antes de usar o username filtro na getAccount() API.
• getAllAccounts() retornará várias contas se você tiver feito várias solicitações de token interativas e o usuário tiver selecionado contas diferentes em duas ou mais dessas interações. Talvez seja necessário passar prompt: "select_account" ou prompt: "login" para a API de logon ou acquireToken interativa para Microsoft Entra ID exibir a tela de seleção da conta após a primeira interação.
• As APIs da conta retornam o estado da conta local e não refletem necessariamente o estado do servidor. Eles retornam contas que entraram anteriormente neste aplicativo usando MSAL.js e a sessão do servidor pode ou não estar ativa.
• Dois aplicativos hospedados em domínios diferentes não compartilham o estado da conta devido ao armazenamento do navegador ser semeado pelo domínio.
• getAllAccounts() não é ordenado e não tem a garantia de estar na mesma ordem em várias chamadas
• Cada chamada bem-sucedida para uma API de logon ou acquireToken retornará exatamente uma conta