Logon único com o MSAL.js

  • Artigo

O SSO (logon único) fornece uma experiência contínua reduzindo o número de vezes que as credenciais são solicitadas aos usuários. Os usuários inserem as credenciais uma vez e a sessão estabelecida pode ser reutilizada por outros aplicativos no mesmo dispositivo sem solicitar mais informações.

O Microsoft Entra ID permite o SSO habilitando um cookie de sessão na primeira autenticação do usuário. A MSAL.js também armazena em cache os tokens de ID e de acesso do usuário no armazenamento do navegador por domínio do aplicativo. Esses dois mecanismos, cookie de sessão do Microsoft Entra e cache da MSAL (Biblioteca de Autenticação da Microsoft) são independentes um do outro, mas funcionam juntos para fornecer comportamento de SSO.

SSO entre as guias do navegador para o mesmo aplicativo

Quando um usuário abre um aplicativo em várias guias e entra em uma delas, ele é conectado aos mesmos aplicativos abertos nas outras guias sem ser receber outras solicitações. Para fazer isso, você precisa definir o cacheLocation no objeto de configuração do MSAL.js como localStorage, conforme mostrado no seguinte exemplo:

const config = {
  auth: {
    clientId: "1111-2222-3333-4444-55555555",
  },
  cache: {
    cacheLocation: "localStorage",
  },
};

const msalInstance = new msal.PublicClientApplication(config);

Nesse caso, as instâncias de aplicativo em guias diferentes do navegador usam o mesmo cache MSAL, compartilhando assim o estado de autenticação entre elas. Você também pode usar eventos MSAL para atualizar instâncias de aplicativo quando um usuário faz logon de outra guia ou janela do navegador. Para obter mais informações, confira: Sincronizando o estado conectado entre guias e janelas

SSO entre aplicativos diferentes

Quando um usuário for autenticado, um cookie de sessão será definido no domínio do Microsoft Entra no navegador. A MSAL.js se baseia nesse cookie de sessão para fornecer o SSO ao usuário entre diferentes aplicativos. Em particular, MSAL.js oferece o método ssoSilent para entrar no usuário e obter tokens sem interação. Entretanto, se o usuário tiver várias contas de usuário na sessão com o Microsoft Entra ID, será solicitado que ele escolha uma delas para entrar. Como tal, há duas maneiras de alcançar o SSO usando o método ssoSilent.

Com dica de usuário

Para melhorar o desempenho e garantir que o servidor de autorização procure a sessão de conta correta, você pode passar uma das seguintes opções no objeto de solicitação do método ssoSilent para obter o token silenciosamente.

É recomendável usar a login_hintdeclaração de token de ID opcional fornecida para ssoSilent como loginHint, por ser a dica de conta mais confiável de solicitações silenciosas e interativas.

Usando uma dica de logon

A declaração opcional login_hint fornece uma dica ao Microsoft Entra ID sobre a conta de usuário que está tentando entrar. Para ignorar a solicitação de seleção de conta, que normalmente mostrada durante solicitações de autenticação interativas, forneça a loginHint conforme mostrado:

const silentRequest = {
    scopes: ["User.Read", "Mail.Read"],
    loginHint: "user@contoso.com"
};

try {
    const loginResponse = await msalInstance.ssoSilent(silentRequest);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(silentRequest).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Neste exemplo, loginHint contém o email ou UPN do usuário, que é usado como uma dica durante solicitações interativas de token. A dica pode ser passada entre aplicativos para facilitar o SSO silencioso, em que o aplicativo A pode conectar um usuário, ler a loginHint e, em seguida, enviar a declaração e o contexto atual do locatário para o aplicativo B. O Microsoft Entra ID tentará preencher previamente o formulário de login ou ignorar o prompt de seleção da conta e prosseguir diretamente com o processo de autenticação para o usuário especificado.

Se as informações na declaração login_hint não corresponderem a nenhum usuário existente, ele será redirecionado para passar pela experiência de login padrão, incluindo a seleção de conta.

Usando uma ID de sessão

Para usar uma sessão de ID, adicione sid como uma declaração opcional aos tokens de ID do aplicativo. A declaração sid permite que o aplicativo identifique a sessão do usuário no Microsoft Entra independentemente do nome da conta ou do nome de usuário dele. Para saber como adicionar declarações opcionais como sid, confira Fornecer declarações opcionais ao aplicativo. Use a SID (ID de sessão) em solicitações de autenticação silenciosas que você faz com ssoSilent na MSAL.js.

const request = {
  scopes: ["user.read"],
  sid: sid,
};

 try {
    const loginResponse = await msalInstance.ssoSilent(request);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(request).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Usando um objeto de conta

Se você souber as informações da conta de usuário, também poderá recuperar a conta de usuário usando os métodos getAccountByUsername() ou getAccountByHomeId():

const username = "test@contoso.com";
const myAccount  = msalInstance.getAccountByUsername(username);

const request = {
    scopes: ["User.Read"],
    account: myAccount
};

try {
    const loginResponse = await msalInstance.ssoSilent(request);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(request).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Sem dica de usuário

Você pode tentar usar o método ssoSilent sem passar account, sid nem login_hint conforme mostrado no seguinte código:

const request = {
    scopes: ["User.Read"]
};

try {
    const loginResponse = await msalInstance.ssoSilent(request);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(request).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

No entanto, haverá uma probabilidade de erros de entrada silenciosa se o aplicativo tiver vários usuários em uma só sessão do navegador ou se o usuário tiver várias contas para essa única sessão do navegador. O seguinte erro poderá ser exibido se várias contas estiverem disponíveis:

InteractionRequiredAuthError: interaction_required: AADSTS16000: Either multiple user identities are available for the current request or selected account is not supported for the scenario.

O erro indica que o servidor não conseguiu determinar em qual conta entrar e exigirá um dos parâmetros do exemplo anterior (account, login_hint, sid) ou uma entrada interativa para escolher a conta.

Considerações ao usar o ssoSilent

URI de redirecionamento (URL de resposta)

Para melhor desempenho e para ajudar a evitar problemas, defina como redirectUri para uma página em branco ou outra página que não usa MSAL.

  • Se os usuários do aplicativo usarem apenas métodos pop-up e silenciosos, defina o redirectUri no objeto de configuração PublicClientApplication.
  • Se o aplicativo também usar métodos de redirecionamento, defina redirectUri para cada solicitação.

Cookies de terceiros

ssoSilent tenta abrir um iframe oculto e reutilizar uma sessão existente com Microsoft Entra ID. Isso não funcionará em navegadores que bloqueiam cookies de terceiros, como o Safari, e levará a um erro de interação:

InteractionRequiredAuthError: login_required: AADSTS50058: A silent sign-in request was sent but no user is signed in. The cookies used to represent the user's session were not sent in the request to Azure AD

Para resolver o erro, o usuário precisa criar uma solicitação de autenticação interativa usando o loginPopup() ou loginRedirect(). Em alguns casos, o valor do prompt nenhum pode ser usado junto com um método de MSAL.js interativo para alcançar o SSO. Confira Solicitações interativas com prompt=none para obter mais informações. Se você já tiver as informações de entrada do usuário, poderá passar os parâmetros opcionais loginHint ou sid para entrar em uma conta específica.

Negando o SSO com prompt=login

Se você preferir que o Microsoft Entra ID solicite que o usuário insira credenciais, apesar de haver uma sessão ativa com o servidor de autorização, use o parâmetro de prompt login nas solicitações com o MSAL.js. Consulte Comportamento de prompt da MSAL.js para obter mais informações.

Compartilhando o estado de autenticação entre ADAL.js e MSAL.js

A MSAL.js oferece paridade de recursos com a ADAL.js para cenários de autenticação do Microsoft Entra. Para facilitar a migração de ADAL.js para MSAL.js e compartilhar o estado de autenticação entre aplicativos, a biblioteca lê o token de ID que representa a sessão do usuário no cache da ADAL.js. Para aproveitar isso ao migrar da ADAL.js, você precisará garantir que as bibliotecas estejam usando localStorage para os tokens de cache. Defina cacheLocation como localStorage na configuração da MSAL.js e da ADAL.js durante a inicialização da seguinte maneira:


// In ADAL.js
window.config = {
  clientId: "1111-2222-3333-4444-55555555",
  cacheLocation: "localStorage",
};

var authContext = new AuthenticationContext(config);

// In latest MSAL.js version
const config = {
  auth: {
    clientId: "1111-2222-3333-4444-55555555",
  },
  cache: {
    cacheLocation: "localStorage",
  },
};

const msalInstance = new msal.PublicClientApplication(config);

Próximas etapas

Para obter mais informações sobre SSO, confira: