Compartilhar via

Tratar erros e exceções em MSAL.js

  • Artigo

Este artigo fornece uma visão geral dos diferentes tipos de erros e das recomendações para lidar com erros comuns de entrada.

Noções básicas de tratamento de erros da MSAL

As exceções na Biblioteca de Autenticação da Microsoft (MSAL) são destinadas aos desenvolvedores de aplicativos para solucionar problemas, não para exibi-los aos usuários finais. Mensagens de exceção não são localizadas.

Ao processar exceções e erros, é possível usar o próprio tipo de exceção e o código de erro para distinguir entre exceções. Para obter uma lista de códigos de erro, consulte Códigos de erro de autenticação e autorização do Microsoft Entra.

Durante a experiência de entrada, você pode encontrar erros sobre consentimentos, Acesso Condicional (MFA, Gerenciamento de Dispositivo, Restrições baseadas em local), emissão e resgate de token e propriedades de usuário.

A seção a seguir fornece mais detalhes sobre o tratamento de erros para seu aplicativo.

Tratamento de erro em MSAL.js

A MSAL.js fornece objetos de erro que resume e classificam os diferentes tipos de erros comuns. Ela também fornece a interface para acessar detalhes específicos dos erros, como mensagens de erro, para tratá-los adequadamente.

Objeto de erro

export class AuthError extends Error {
    // This is a short code describing the error
    errorCode: string;
    // This is a descriptive string of the error,
    // and may also contain the mitigation strategy
    errorMessage: string;
    // Name of the error class
    this.name = "AuthError";
}

Ao estender a classe do erro, você terá acesso às seguintes propriedades:

  • AuthError.message: Igual a errorMessage.
  • AuthError.stack: Rastreamento de pilha para erros gerados.

Tipos de erro

Os tipos de erro a seguir estão disponíveis:

  • AuthError: Classe de erro base para a biblioteca MSAL.js, também usada para erros inesperados.

  • ClientAuthError: classe de erro, a qual indica um problema com a Autenticação de Cliente. A maioria dos erros originados da biblioteca são ClientAuthErrors. Esses erros resultam de coisas como chamar um método de logon quando o logon já está em andamento, q o usuário cancela o logon, e assim por diante.

  • ClientConfigurationError: classe de erro que estende ClientAuthError. É gerado antes que as solicitações sejam feitas quando os parâmetros de configuração do usuário fornecidos estiverem malformados ou ausentes.

  • ServerError: classe de erro, a qual representa as cadeias de caracteres de erro enviadas pelo servidor de autenticação. Esses erros podem ser parâmetros ou formatos da solicitação inválidos ou qualquer outro erro que impeça o servidor de autenticar ou autorizar o usuário.

  • InteractionRequiredAuthError: classe de erro, a qual estende o ServerError para representar erros do servidor que exigem uma chamada interativa. Esse erro será gerado por acquireTokenSilent caso o usuário precise interagir com o servidor para fornecer credenciais ou consentimentos para autenticação/autorização. São exemplos de códigos de erro: "interaction_required", "login_required" e "consent_required".

Para o tratamento de erro nos fluxos de autenticação com métodos de redirecionamento (loginRedirect, acquireTokenRedirect), você precisará lidar com a promessa de redirecionamento, que é chamada com sucesso ou fracasso após o redirecionamento usando o método handleRedirectPromise() da seguinte forma:

const msal = require('@azure/msal-browser');
const myMSALObj = new msal.PublicClientApplication(msalConfig);

// Register Callbacks for redirect flow
myMSALObj.handleRedirectPromise()
    .then(function (response) {
        //success response
    })
    .catch((error) => {
        console.log(error);
    })
myMSALObj.acquireTokenRedirect(request);

Os métodos para experiência de pop-up (loginPopup, acquireTokenPopup) retornam promessas, de modo que seja possível usar o padrão de promessa (.then e .catch) para tratá-los, conforme mostrado:

myMSALObj.acquireTokenPopup(request).then(
    function (response) {
        // success response
    }).catch(function (error) {
        console.log(error);
    });

Erros que exigem interação

Um erro será retornado quando você tentar usar um método não interativo de aquisição de um token, como acquireTokenSilent, sem que a MSAL pudesse fazê-lo silenciosamente.

As possíveis razões são:

  • é necessário entrar
  • é necessário consentir
  • é necessário passar por uma experiência de autenticação multifator.

A correção é chamar um método interativo como acquireTokenPopup ou acquireTokenRedirect:

// Request for Access Token
myMSALObj.acquireTokenSilent(request).then(function (response) {
    // call API
}).catch( function (error) {
    // call acquireTokenPopup in case of acquireTokenSilent failure
    // due to interaction required
    if (error instanceof InteractionRequiredAuthError) {
        myMSALObj.acquireTokenPopup(request).then(
            function (response) {
                // call API
            }).catch(function (error) {
                console.log(error);
            });
    }
});

Acesso condicional e desafio de declarações

Ao obter tokens silenciosamente, o aplicativo poderá receber erros quando um desafio de declarações de acesso condicional, como a Política de MFA, for exigido por uma API que você está tentando acessar.

O padrão para tratar desse erro é obter um token de forma interativa usando a MSAL. Isso solicita a participação do usuário e oferece a oportunidade para atender à política de acesso condicional exigida.

Em determinados casos, ao chamar uma API que exige acesso condicional, você poderá receber um desafio de declarações no erro da API. Por exemplo, se a política de acesso condicional tiver um dispositivo gerenciado (Intune), o erro será semelhante a AADSTS53000: O dispositivo deverá ser gerenciado para acessar este recurso ou algo similar. Nesse caso, é possível passar as declarações na chamada do token de aquisição, de modo que o usuário seja solicitado a atender à política apropriada.

Ao obter tokens silenciosamente (com acquireTokenSilent) usando MSAL.js, o aplicativo poderá receber erros quando a API que você está tentando acessar exige um desafio de declarações de Acesso Condicional, como a Política de MFA.

O padrão para tratar esse erro é fazer uma chamada interativa para obter o token em MSAL.js, como acquireTokenPopup ou acquireTokenRedirect, conforme no exemplo a seguir:

myMSALObj.acquireTokenSilent(accessTokenRequest).then(function(accessTokenResponse) {
    // call API
}).catch(function(error) {
    if (error instanceof InteractionRequiredAuthError) {
    
        // extract, if exists, claims from the error object
        if (error.claims) {
            accessTokenRequest.claims = error.claims,
        
        // call acquireTokenPopup in case of InteractionRequiredAuthError failure
        myMSALObj.acquireTokenPopup(accessTokenRequest).then(function(accessTokenResponse) {
            // call API
        }).catch(function(error) {
            console.log(error);
        });
    }
});

A obtenção interativa do token solicita a participação do usuário e oferece a oportunidade para atender à política de acesso condicional exigida.

Ao chamar uma API que exige acesso condicional, você poderá receber um desafio de declarações no erro da API. Neste caso, você pode passar as declarações devolvidas no erro para o parâmetro claims no objeto de solicitação de token de acesso para satisfazer a política apropriada.

Veja Como usar as APIs habilitadas para a Avaliação contínua de acesso em seus aplicativos para obter mais detalhes.

Usando outras estruturas

O uso de kits de ferramentas como o Tauri para SPAs (aplicativos de página única) registrados com a plataforma de identidade não é reconhecido para aplicativos de produção. Os SPAs só dão suporte a URLs que começam com https para aplicativos de produção e http://localhost para desenvolvimento local. Prefixos como tauri://localhost não podem ser usados para aplicativos de navegador. Esse formato só pode ter suporte para aplicativos móveis ou Web, pois eles têm um componente confidencial, ao contrário dos aplicativos do navegador.

Tentar novamente após erros e exceções

Você deve implementar suas próprias políticas de repetição ao chamar a MSAL. A MSAL faz chamadas HTTP para o serviço do Microsoft Entra e, ocasionalmente, podem ocorrer falhas. Por exemplo, a rede pode ficar inoperante ou o servidor está sobrecarregado.

HTTP 429

Quando o STS estiver sobrecarregado com muitas solicitações, ele retornará o erro HTTP 429 com uma dica sobre quanto tempo você deve aguardar até poder tentar novamente no campo de resposta Retry-After.

Próximas etapas

Considere habilitar o Registro em log no MSAL.js para ajudá-lo a diagnosticar e depurar problemas