Desligar utilizadores

Antes de começares aqui, certifica-te de que compreendes como iniciar sessão, adquirir tokens e gerir a vida útil dos tokens.

Encerrar sessão

O processo de logout para o MSAL tem dois passos.

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

O PublicClientApplication objeto expõe duas APIs que realizam estas ações.

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

Estas APIs limpam a cache de tokens e quaisquer dados de utilizador e de sessão e, em seguida, redirecionam a janela do navegador ou a janela pop-up para a página de fim de sessão do servidor. O servidor irá então pedir ao utilizador que selecione a conta da qual gostaria de sair e redirecione de volta para si postLogoutRedirectUri , desde que sejam cumpridas as seguintes condições:

1. O URI é registado como um URL de resposta no registo da aplicação
2. O URI é fornecido como o postLogoutRedirectUri quer na configuração PublicClientApplication quer no pedido de logout
3. O utilizador mantém uma sessão ativa com o fornecedor de identidade
4. (Cenários MSA) Está configurado um URL de terminação de sessão do canal front-end no registo da aplicação

Se alguma das condições acima não for cumprida, a página (ou a janela pop-up) permanecerá na página de logout do fornecedor de identidade.

IMPORTANTE: Se esta navegação de logout for interrompida de alguma forma, a sua cache MSAL pode ser limpa, mas a sessão pode continuar a persistir no servidor. Certifique-se de que a navegação está totalmente concluída antes de regressar à sua candidatura.

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

Podem ser fornecidas opções de configuração a cada uma das APIs de logout para personalizar o comportamento:

• logoutPedido de redirecionamento
• Pedido de logoutPopup

logoutRedirect

A utilização de logoutRedirect irá limpar a cache local dos tokens de utilizador e, em seguida, redirecionará a janela para a página de fim de sessão do servidor. A promessa devolvida por logoutRedirect não é suposto ser resolvida, mas pode aguardá-la se precisar de bloquear a execução de outro código antes de o redirecionamento ser iniciado.

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

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

Saltar o encerramento do servidor

Se quiser que a sua aplicação efetue apenas o encerramento de sessão local, pode fornecer uma função de callback ao parâmetro onRedirectNavigate no pedido e fazer com que essa função devolva 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 encerramento do servidor num popup, permitindo que a sua aplicação mantenha o seu estado atual. Por isso, há algumas considerações adicionais ao logoutRedirect optar por usar pop-ups para terminar sessão:

• Espera-se que a promessa retornada por logoutPopup seja resolvida depois de o pop-up fechar
• postLogoutRedirectUri é necessário para que o MSAL possa fechar o popup quando a saída de sessão estiver concluída
• postLogoutRedirectUri será aberto na janela pop-up, não no quadro principal. Se precisares que a tua aplicação de nível superior seja redirecionada após o término de sessão, podes usar o parâmetro mainWindowRedirectUri no pedido de término de sessão.

Podem ser fornecidas opções de configuração 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
        }
    }
});

Encerramento de sessão sem necessidade

Se a sua aplicação cliente tiver a afirmação opcional login_hint ativada para tokens de ID, pode tirar partido da afirmação login_hint do token de ID para realizar um logout "silencioso" ou sem pedido ao utilizar logoutRedirect ou logoutPopup. Existem duas formas de conseguir um encerramento de sessão sem aviso:

Opção 1: Deixar que a MSAL analise automaticamente o login_hint das reivindicações do ID token da conta

A primeira e mais simples opção é fornecer o objeto de conta para o qual quer terminar a sessão à API de logout. O MSAL verifica se a declaração login_hint está disponível no token de ID da conta e adiciona-a automaticamente ao pedido de encerramento de sessão como logout_hint para ignorar o pedido 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 no pedido de logout

Em alternativa, se preferires definir manualmente o logoutHint, podes extrair a claim login_hint da tua aplicação e definir esse valor como logoutHint no pedido 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 });

Nota: Dependendo da API que escolher (redirecionar/popup), a aplicação continuará a redirecionar ou abrir um pop-up para terminar a sessão do servidor. A diferença é que o utilizador não verá nem terá de interagir com o prompt seletor de conta do servidor.

Terminação de sessão pelo canal frontal

O Microsoft Entra ID e o Azure AD B2C suportam a funcionalidade de logout do canal frontal OAuth, que permite o single sign out em todas as aplicações quando um utilizador inicia logout. Para tirar partido desta funcionalidade com MSAL.js, execute os seguintes passos:

1. Na sua aplicação, crie uma página dedicada ao logout. Esta página não deve desempenhar qualquer outra função, como adquirir tokens durante o carregamento da página (ver detalhes abaixo). Tenha em atenção que esta página será carregada num iframe oculto e, para os utilizadores 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é à página Autenticação da sua aplicação e registe a página do passo um em URL de terminação de sessão do canal frontal. Nota, esta página deve ser carregada via https.

Requisitos para a página de logout do canal principal

A página utilizada para o encerramento de sessão do canal frontal deve ser estruturada da seguinte forma:

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

Example:

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 utilizador termina a sessão noutra aplicação, o URL de encerramento de sessão do canal frontal da sua aplicação será carregado num iframe oculto, e o MSAL.js limpará a cache para concluir o encerramento único de sessão.

Exemplos de terminação de sessão no canal front-channel

Os exemplos seguintes demonstram como implementar logout no canal frontal usando MSAL.js:

• MSAL Angular v2: Amostra Angular 11
• MSAL React: Amostra do Router React

Eventos

Se diferentes partes da sua aplicação precisarem de reagir ao estado de sessão terminada sem acesso direto à promessa devolvida por logoutRedirect ou logoutPopup, pode usar a API de eventos.

Serão gerados eventos quando o logout for bem-sucedido ou falhar e quando o popup for aberto quando se utiliza logoutPopup.

Notas Importantes

• Se nenhuma conta for passada para a API de logout, ou não houver um objeto EndSessionRequest, ela sai de todas as contas.
• Se uma conta for passada para a API de logout, a MSAL só irá limpar tokens relacionados com essa conta.
• A desconexão do servidor é uma funcionalidade de conveniência e, como tal, é feita com o melhor esforço. As APIs de logout serão resolvidas com sucesso desde que a cache local da aplicação tenha sido limpa com sucesso, independentemente de a saída do servidor ser bem-sucedida ou não.

Próximas Etapas

Aprofunde temas mais avançados, tais como:

• Caching
• Opções Avançadas de Configuração