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

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

Noções básicas de gestão de erros MSAL

As exceções na Biblioteca de Autenticação da Microsoft (MSAL) destinam-se aos programadores de aplicações para resolver problemas, não para serem exibidas aos utilizadores finais. As mensagens de exceção não são localizadas.

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

Durante a experiência de login, pode encontrar erros sobre consentimentos, Acesso Condicional (MFA, Gestão de Dispositivos, restrições baseadas na localização), emissão e resgate de tokens, e propriedades dos utilizadores.

A secção seguinte fornece mais detalhes sobre o tratamento de erros na sua aplicação.

Tratamento de erros em MSAL.js

MSAL.js fornece objetos de erro que abstraem e classificam os diferentes tipos de erros comuns. Também fornece uma interface para aceder a detalhes específicos dos erros, como mensagens de erro, para os tratar 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, tem acesso às seguintes propriedades:

  • AuthError.message: Igual ao errorMessage.
  • AuthError.stack: Stack trace para erros gerados.

Tipos de erro

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

  • AuthError: Classe base de erro 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. Estes erros resultam de coisas como chamar um método de login quando o login já está em andamento, o utilizador cancelar o login, e assim sucessivamente.

  • ClientConfigurationError: Classe de erro, que estende ClientAuthError, que é lançada antes de serem feitas requisições quando os parâmetros de configuração do utilizador fornecidos estão malformados ou em falta.

  • ServerError: Classe de erro, representa as cadeias de erro enviadas pelo servidor de autenticação. Estes erros podem ser formatos ou parâmetros de pedido inválidos, ou quaisquer outros erros que impeçam o servidor de autenticar ou autorizar o utilizador.

  • InteractionRequiredAuthError: Classe de erro, estende ServerError para representar erros do servidor, que requerem uma chamada interativa. Este erro é gerado por acquireTokenSilent quando o utilizador tem de interagir com o servidor para fornecer credenciais ou dar consentimento para autenticação/autorização. Os códigos de erro incluem "interaction_required", "login_required", e "consent_required".

Para o tratamento de erros em fluxos de autenticação com métodos de redirecionamento (loginRedirect, acquireTokenRedirect), terá de tratar da promessa de redirecionamento, que é chamada com sucesso ou falha após o redirecionamento usando o handleRedirectPromise() método seguinte:

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 a experiência de pop-up (loginPopup, acquireTokenPopup) devolvem promessas, pelo que podes usar o padrão de promessa (.then e .catch) para lidar com elas conforme mostrado:

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

Erros que requerem interação

Um erro é devolvido quando tenta usar um método não interativo para adquirir um token como acquireTokenSilent, mas a MSAL não conseguiu fazê-lo silenciosamente.

As possíveis razões são:

  • Precisas de iniciar sessão
  • Tem de dar o seu consentimento
  • Precisa de passar por uma experiência de autenticação multifator.

A remediação consiste em 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 desafios de sinistros

Ao obter tokens silenciosamente, a sua aplicação pode receber erros quando um pedido de reivindicações de Acesso Condicional, como uma política de MFA, for exigido pela API à qual está a tentar aceder.

O padrão para lidar com este erro é adquirir interativamente um token usando MSAL. Isto incita o utilizador e dá-lhe a oportunidade de cumprir a política de Acesso Condicional exigida.

Em determinados casos, ao chamar uma API que requer Acesso Condicional, pode receber um pedido de declarações na mensagem de erro da API. Por exemplo, se a política de Acesso Condicional for ter um dispositivo gerido (Intune), o erro será algo como AADSTS53000: O seu dispositivo é obrigado a ser gerido para aceder a este recurso ou algo semelhante. Neste caso, pode passar as declarações na chamada de aquisição de token para que o utilizador seja solicitado a satisfazer a política adequada.

Ao obter tokens de forma silenciosa (utilizando acquireTokenSilent) com o MSAL.js, a sua aplicação pode deparar-se com erros quando um desafio de reivindicações de Acesso Condicional, como, por exemplo, uma política de MFA, é exigido pela API à qual está a tentar aceder.

O padrão para lidar com este erro é fazer uma chamada interativa para adquirir token em MSAL.js como acquireTokenPopup ou acquireTokenRedirect como no seguinte exemplo:

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 utilizador e dá-lhe a oportunidade de cumprir a política de Acesso Condicional exigida.

Ao chamar uma API que requer Acesso Condicional, pode receber um pedido de reivindicações na resposta de erro da API. Neste caso, pode passar as alegações devolvidas no erro para o parâmetro claims no objeto de pedido de token de acesso para cumprir a política adequada.

Veja Como usar APIs habilitadas pela Avaliação de Acesso Contínuo nas suas aplicações para mais detalhes.

Utilização de outros frameworks

O uso de kits de ferramentas como o Tauri para aplicações de página única registadas (SPAs) com a plataforma de identidade não é reconhecido para aplicações de produção. Os SPAs só suportam URLs que começam com https para aplicações de produção e http://localhost para desenvolvimento local. Prefixos como tauri://localhost não podem ser usados em aplicações de navegador. Este formato só pode ser suportado para aplicações móveis ou web, pois têm um componente confidencial, ao contrário das aplicações de navegador.

Tentar novamente após erros e exceções

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

HTTP 429

Quando o Service Token Server (STS) está sobrecarregado com demasiados pedidos, devolve o erro HTTP 429 com uma dica sobre quanto tempo demora até poderes tentar novamente no campo de resposta Retry-After.

Passos seguintes

Considere ativar o registo no MSAL.js para o ajudar a diagnosticar e a depurar problemas

  • Última atualização a