Tratar erros e exceções em MSAL.js

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

Noções básicas sobre o tratamento de erros do MSAL

As exceções no Biblioteca do Microsoft Authenticator (MSAL) destinam-se aos desenvolvedores de aplicativos a solucionar problemas, não para exibição para usuários finais. As mensagens de exceção não são localizadas.

Ao processar exceções e erros, você pode usar o tipo de exceção em si e o código de erro para distinguir entre exceções. Para obter uma lista de códigos de erro, consulte Microsoft Entra códigos de erro de autenticação e autorização.

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

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

Tratamento de erros no MSAL.js

MSAL.js fornece objetos de erro que abstraem e classificam os diferentes tipos de erros comuns. Ele também fornece uma interface para acessar detalhes específicos dos erros, como mensagens de erro, para lidar com eles 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 de erro, você tem acesso às seguintes propriedades:

  • AuthError.message: o mesmo que o errorMessage.
  • AuthError.stack: rastreamento da pilha de erros lançados.

Tipos de erro

Os seguintes tipos de erro estão disponíveis:

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

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

  • ClientConfigurationError: classe de erro que estende ClientAuthError, lançada 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, representa as cadeias de caracteres de erro enviadas pelo servidor de autenticação. Esses erros podem ser formatos ou parâmetros de solicitação inválidos ou quaisquer outros erros que impeçam o servidor de autenticar ou autorizar o usuário.

  • InteractionRequiredAuthError: classe de erro, estende-se ServerError para representar erros de servidor, que exigem uma chamada interativa. Esse erro será gerado acquireTokenSilent se o usuário for obrigado a interagir com o servidor para fornecer credenciais ou consentimento para autenticação/autorização. Os códigos de erro incluem "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 é retornado quando você tenta usar um método não interativo de aquisição de um token como acquireTokenSilent, mas a MSAL não pôde fazer isso silenciosamente.

As possíveis razões são:

  • você precisa entrar
  • você precisa consentir
  • você precisa passar por um processo 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, seu aplicativo pode receber mensagens de erro quando um questionamento de declarações de Acesso Condicional, como uma política de MFA, for exigido por uma API que você está tentando acessar.

O padrão para lidar com esse erro é adquirir interativamente um token usando MSAL. Isso solicita a participação do usuário e oferece a oportunidade para atender à política de acesso condicional exigida.

Em alguns casos, ao chamar uma API que exige o acesso condicional, você poderá receber um desafio de declarações no erro da API. Por exemplo, se a política de Acesso Condicional for ter um dispositivo gerenciado (Intune), o erro será algo como AADSTS53000: seu dispositivo precisa ser gerenciado para acessar esse recurso ou algo semelhante. Nesse caso, é possível transmitir as declarações na chamada do token de aquisição, de modo que o usuário precise cumprir a política apropriada.

Ao obter tokens silenciosamente (com acquireTokenSilent) usando a MSAL.js, 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 lidar com esse erro é fazer uma chamada interativa para adquirir token em MSAL.js como acquireTokenPopup ou acquireTokenRedirect como 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 o 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 APIs habilitadas para Avaliação de Acesso Contínuo 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 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 diferentemente dos aplicativos do navegador.

Tentar novamente após erros e exceções

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

HTTP 429

Quando o Servidor de Tokens de Serviço (STS) está sobrecarregado com muitas solicitações, ele retorna o erro HTTP 429 com uma dica sobre quanto tempo você poderá esperar até poder tentar novamente no campo de resposta "Tentar novamente após".

Próximas Etapas 

Considere habilitar o log no MSAL.js para ajudar a diagnosticar e depurar problemas

  • Última atualização em