Encerrar a sessão de usuários

Antes de começar aqui, certifique-se de entender como fazer logon, adquirir tokens e gerenciar tempos de vida de token.

Fazendo logout

O processo de saída no MSAL envolve duas etapas.

1. Limpe o cache do MSAL.
2. Limpe a sessão no servidor de identidade.

O PublicClientApplication objeto expõe duas APIs que executam essas ações.

msalInstance.logoutRedirect();
msalInstance.logoutPopup();

Essas APIs limparão o cache do token e quaisquer dados de usuário e de sessão e, em seguida, redirecionarão a janela do navegador ou a janela pop-up para a página de logout do servidor. Em seguida, o servidor solicitará que o usuário selecione a conta da qual deseja sair e o redirecionará de volta ao seu postLogoutRedirectUri, desde que as seguintes condições sejam atendidas:

1. O URI é registrado como uma URL de resposta no registro do aplicativo
2. O URI é fornecido como o postLogoutRedirectUri na configuração PublicClientApplication ou na solicitação de logoff
3. O usuário tem uma sessão ativa com o provedor de identidade
4. (Cenários de MSA) Uma URL de logoff de front-channel é configurada no registro do aplicativo

Se qualquer uma das condições acima não for cumprida, a página (ou a janela pop-up) permanecerá na página de encerramento de sessão do provedor de identidade.

IMPORTANTE: Se esse fluxo de logout for interrompido por qualquer motivo, o cache do MSAL poderá ser limpo, mas a sessão ainda poderá persistir no servidor. Verifique se a navegação foi totalmente concluída antes de retornar ao seu aplicativo.

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.con/{your_tenant_id}',
        redirectUri: 'https://contoso.com',
        postLogoutRedirectUri: 'https://contoso.com/homepage'
    }
};

Objetos de solicitação

Opções de configuração podem ser fornecidas a cada uma das APIs de logoff para personalizar o comportamento:

• solicitação de logoutRedirect
• solicitação de logoutPopup

logoutRedirect

O uso logoutRedirect limpará o cache local de tokens de usuário e redirecionará a janela para a página de saída do servidor. A promessa retornada por logoutRedirect não deve ser resolvida, mas você pode aguardá-la se precisar impedir que outro código seja executado antes que o redirecionamento seja iniciado.

As opções de configuração podem ser fornecidas para personalizar o comportamento:

const currentAccount = msalInstance.getAccount({ homeAccountId });
await msalInstance.logoutRedirect({
    account: currentAccount,
    postLogoutRedirectUri: "https://contoso.com/loggedOut"
});

Ignorando o encerramento de sessão no servidor

Se você quiser que seu aplicativo execute apenas o logout local, poderá fornecer um callback para o parâmetro onRedirectNavigate na requisição e fazer com que esse callback retorne false.

msalInstance.logoutRedirect({
    onRedirectNavigate: (url) => {
        // Return false if you would like to stop navigation after local logout
        return false;
    }
});

logoutPopup

A logoutPopup API abrirá a página de saída do servidor em um pop-up, permitindo que seu aplicativo mantenha seu estado atual. Devido a isso, há algumas considerações adicionais em relação a logoutRedirect ao optar por usar pop-ups para fazer logout:

• Espera-se que a promessa retornada por logoutPopup seja resolvida depois que o pop-up for fechado
• postLogoutRedirectUri é necessário para que a MSAL possa fechar o pop-up quando a saída for concluída
• postLogoutRedirectUri será aberto na janela pop-up, não no quadro principal. Se você precisar que seu aplicativo principal seja redirecionado após o logout, poderá usar o parâmetro mainWindowRedirectUri na solicitação de logout.

As opções de configuração podem ser fornecidas para personalizar o comportamento.

const currentAccount = msalInstance.getAccount({ homeAccountId });
await msalInstance.logoutPopup({
    account: currentAccount,
    postLogoutRedirectUri: "https://contoso.com/loggedOut",
    mainWindowRedirectUri: "https://contoso.com/homePage",
    popupWindowAttributes: {
        popupSize: {
            height: 100,
            width: 100
        },
        popupPosition: {
            top: 100,
            left: 100
        }
    }
});

Logoff sem prompt

Se o aplicativo cliente tiver a declaração opcional login_hint habilitada para tokens de ID, você poderá usar a declaração login_hint do token de ID para realizar um logout "silencioso" ou sem prompt ao usar logoutRedirect ou logoutPopup. Há duas maneiras de realizar um logout sem prompt:

Opção 1: Permitir que a MSAL analise automaticamente a login_hint das declarações de token de ID da conta

A primeira e mais simples opção é passar para a API de logout o objeto da conta para a qual você deseja encerrar a sessão. A MSAL verificará se a declaração login_hint está disponível no token de ID da conta e a adicionará automaticamente à solicitação de encerramento de sessão como logout_hint para ignorar o prompt de seleção de conta.

const currentAccount = msalInstance.getAccount({ homeAccountId });
// The account's ID Token must contain the login_hint optional claim to avoid the account picker
await msalInstance.logoutRedirect({ account: currentAccount});

Opção 2: definir manualmente a opção logoutHint na solicitação de logout

Como alternativa, se você preferir definir manualmente o logoutHint, poderá extrair o claim login_hint no seu aplicativo e defini-lo como o logoutHint na solicitação de logout:

const currentAccount = msalInstance.getAccount({ homeAccountId });

// Extract login hint to use as logout hint
const logoutHint = currentAccount.idTokenClaims.login_hint;
await msalInstance.logoutPopup({ logoutHint: logoutHint });

Observação: dependendo da API escolhida (redirecionamento/pop-up), o aplicativo ainda redirecionará ou abrirá um pop-up para encerrar a sessão do servidor. A diferença é que o usuário não verá ou precisará interagir com o prompt do seletor de conta do servidor.

Logoff de front-channel

O Microsoft Entra ID e o Azure AD B2C oferecem suporte ao recurso de logoff de front-channel do OAuth, que permite o logoff único de todos os aplicativos quando um usuário inicia o logoff. Para aproveitar esse recurso com MSAL.js, execute as seguintes etapas:

1. No seu aplicativo, crie uma página de logout exclusiva. Esta página não deve executar nenhuma outra função, como a aquisição de tokens na carga da página (consulte abaixo para obter detalhes). Observe que esta página será carregada em um iFrame oculto e, para usuários do Microsoft Entra ID e do MSA, incluirá os parâmetros de consulta iss e sid.
2. No centro de administração do Microsoft Entra, navegue até a página Autenticação do seu aplicativo e registre-a desde a etapa um em URL de logoff de front-channel. Observe que esta página deve ser carregada por meio de https.

Requisitos para a página de logout por front-channel

A página usada para logoff de front-channel deve ser construída da seguinte maneira:

1. No carregamento da página, invoque automaticamente a API MSAL logoutRedirect .
2. PublicClientApplication Na configuração, defina system.allowRedirectInIframe como true.
3. Ao invocar logout, recomendamos impedir o redirecionamento no iframe para a página de logoff (consulte acima).

Exemplo:

const msal = new PublicClientApplication({
    auth: {
        clientId: "my-client-id"
    },
    system: {
        allowRedirectInIframe: true
    }
})

// Automatically on page load
msal.logoutRedirect({
    onRedirectNavigate: () => {
        // Return false to stop navigation after local logout
        return false;
    }
});

Agora, quando um usuário fizer logoff de outro aplicativo, a URL de logoff de front-channel do seu aplicativo será carregada em um iFrame oculto, e o MSAL.js limpará seu cache para concluir o logoff único.

Exemplos de logout via canal frontal

Os exemplos a seguir demonstram como implementar o logout de front-channel usando o MSAL.js:

• MSAL Angular v2: exemplo do Angular 11
• MSAL React: exemplo do Roteador React

Eventos

Se diferentes partes do seu aplicativo precisarem reagir ao status de logout sem acesso direto à promessa retornada por logoutRedirect ou logoutPopup, você poderá usar a API de eventos.

Os eventos serão emitidos quando o logoff for bem-sucedido ou falhar e quando a janela pop-up for aberta ao usar logoutPopup.

Notas importantes

• Se nenhuma conta for passada para a API de logoff, ou nenhum objeto EndSessionRequest, o logoff será feito de todas as contas.
• Se uma conta for passada para a API de logoff, a MSAL limpará apenas os tokens relacionados a essa conta.
• O logout do servidor é uma funcionalidade de conveniência e, como tal, é realizado em regime de melhor esforço. As APIs de logoff serão resolvidas desde que o cache do aplicativo local tenha sido limpo, independentemente do êxito ou não da saída do servidor.

Próximas etapas

Examine tópicos mais avançados, como:

• Armazenamento em cache
• Opções avançadas de configuração