Partilhar via

Lidar com erros e exceções no MSAL.js

  • Artigo

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 de tratamento de erros MSAL

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

Ao processar exceções e erros, você pode 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 login, você pode encontrar erros sobre consentimentos, acesso condicional (MFA, gerenciamento de dispositivos, restrições baseadas em localização), 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 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 de erro, você tem acesso às seguintes propriedades:

  • AuthError.message: O mesmo que o errorMessage.
  • AuthError.stack: Rastreamento de pilha para erros lançados.

Tipos de erro

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

  • AuthError: Classe de erro base para a biblioteca 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 que vêm da biblioteca são ClientAuthErrors. Esses erros resultam de coisas como chamar um método de login quando o login já está em andamento, o usuário cancela o login e assim por diante.

  • ClientConfigurationError: Classe de erro que se estende ClientAuthError. Ele é lançado antes que as solicitações sejam feitas quando os parâmetros de configuração do usuário fornecidos estão 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 do servidor, que exigem uma chamada interativa. Este erro é gerado por acquireTokenSilent se o usuário é 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 tratamento de erros em fluxos de autenticação com métodos de redirecionamento (loginRedirect, acquireTokenRedirect), você precisará lidar com a promessa de redirecionamento, que é chamada com sucesso ou falha após o redirecionamento usando o handleRedirectPromise() método da seguinte maneira:

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 pop-up (loginPopup, acquireTokenPopup) retornam promessas, para que você possa usar o padrão de promessa (.then e .catch) para manipulá-las 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 adquirir um token como acquireTokenSilent, mas a MSAL não conseguiu fazê-lo silenciosamente.

As possíveis razões são:

  • Precisa de iniciar sessão
  • você precisa consentir
  • Você precisa passar por uma experiência de autenticação multifator.

A remediaçã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 contestações de reclamações

Ao obter tokens silenciosamente, seu aplicativo pode receber erros quando um desafio de declarações de Acesso Condicional, como a política de MFA, é 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 ao usuário e lhe dá a oportunidade de satisfazer a política de Acesso Condicional necessária.

Em certos casos, ao chamar uma API que requer Acesso Condicional, você pode 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á algo como AADSTS53000: Seu dispositivo precisa ser gerenciado para acessar este recurso ou algo semelhante. Nesse caso, você pode passar as declarações na chamada de token de aquisição para que o usuário seja solicitado a satisfazer a política apropriada.

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

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 aquisição interativa do token solicita ao usuário e lhe dá a oportunidade de satisfazer a política de Acesso Condicional necessária.

Ao chamar uma API que requer Acesso Condicional, você pode receber um desafio de declarações no erro da API. Nesse caso, você pode passar as declarações retornadas no erro para o claims parâmetro no objeto de solicitação de token de acesso para satisfazer a política apropriada.

Consulte Como usar APIs habilitadas para 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 aplicativos de página única (SPAs) registrados com a plataforma de identidade não é reconhecido para aplicativos de produção. Os SPAs suportam apenas 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 do navegador. Este formato só pode ser suportado para aplicações móveis ou Web, uma vez que têm um componente confidencial, ao contrário das aplicações do navegador.

Repetindo após erros e exceções

Espera-se que você implemente suas próprias políticas de repetição ao chamar o MSAL. MSAL faz chamadas HTTP para o serviço Microsoft Entra e, ocasionalmente, podem ocorrer falhas. Por exemplo, a rede pode ficar inativa ou o servidor está sobrecarregado.

HTTP 429

Quando o Servidor de Token de Serviço (STS) está sobrecarregado com muitas solicitações, ele retorna o erro HTTP 429 com uma dica sobre quanto tempo até que você possa tentar novamente no campo de Retry-After resposta.

Próximos passos

Considere ativar o Login MSAL.js para ajudá-lo a diagnosticar e depurar problemas