Control de errores y excepciones en MSAL.js

En este artículo se proporciona información general sobre los distintos tipos de errores y las recomendaciones para controlar los errores de inicio de sesión comunes.

Aspectos básicos del control de errores en MSAL

Las excepciones de la Biblioteca de autenticación de Microsoft (MSAL) están diseñadas para que los desarrolladores de aplicaciones solucionen problemas y no para mostrarse a los usuarios finales. Los mensajes de excepción no están traducidos.

Cuando procesa excepciones y errores, puede usar el propio tipo de excepción y el código de error para distinguir entre las excepciones. Para ver una lista con los códigos de error, consulte Códigos de error de autenticación y autorización de Microsoft Entra.

Durante la experiencia de inicio de sesión, puede encontrar errores de consentimiento, de acceso condicional (MFA, administración de dispositivos, restricciones basadas en la ubicación), de emisión y canje de tokens, y de las propiedades del usuario.

En la sección siguiente se proporcionan más detalles sobre el control de errores de la aplicación.

Control de errores en MSAL.js

MSAL.js proporciona objetos de error que abstraen y clasifican los distintos tipos de errores comunes. También proporciona una interfaz para acceder a detalles específicos de los errores, como los mensajes de error, para controlarlos de manera adecuada.

Objeto de error

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";
}

Si extiende la clase de error, tendrá acceso a las siguientes propiedades:

• AuthError.message: igual que errorMessage.
• AuthError.stack: Seguimiento de la pila de los errores que se produjeron.

Tipos de errores

Están disponibles los siguientes tipos de errores:

• AuthError: Clase de error básica para la biblioteca MSAL.js. También se usa para los errores inesperados.

• ClientAuthError: clase de error que indica un problema con la autenticación de cliente. La mayoría de los errores que proceden de la biblioteca son del tipo ClientAuthErrors. Estos errores son consecuencia de cosas como una llamada a un método de inicio de sesión con el inicio de sesión ya en curso, cuando el usuario cancela el inicio de sesión, etc.

• ClientConfigurationError: clase de error que extiende ClientAuthError. Se produce antes de que se realicen las solicitudes si los parámetros de configuración de un usuario determinado faltan o tienen un formato incorrecto.

• ServerError: clase de error que representa las cadenas de error que envía el servidor de autenticación. Estos errores pueden ser formatos o parámetros de solicitud no válidos o cualquier otro error que impida al servidor autenticar o autorizar al usuario.

• InteractionRequiredAuthError: clase de error que extiende ServerError para representar errores de servidor que requieren una llamada interactiva. acquireTokenSilent genera este error si se solicita al usuario que interactúe con el servidor para proporcionar credenciales o consentimiento para la autenticación o autorización. Los códigos de error incluyen "interaction_required", "login_required" y "consent_required".

Para el control de errores en flujos de autenticación con métodos de redireccionamiento (loginRedirect, acquireTokenRedirect), deberá controlar la promesa de redirección, a la que se llama correctamente o con error después del redireccionamiento mediante el método handleRedirectPromise() de la siguiente manera:

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);

Los métodos de la experiencia emergente (loginPopup, acquireTokenPopup) devuelven promesas, de forma que puede usar el patrón de promesa (.then y .catch) para controlarlas de la siguiente manera:

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

Errores que requieren interacción

Se devuelve un error al intentar usar un método no interactivo para adquirir un token (por ejemplo, acquireTokenSilent) y que MSAL no pudiera hacerlo de manera silenciosa.

Los posibles motivos son:

• Debe iniciar sesión
• Debe dar su consentimiento
• Debe pasar por una experiencia de autenticación multifactor.

La solución consiste en llamar a un método interactivo como acquireTokenPopup o 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);
            });
    }
});

Acceso condicional y desafíos de notificaciones

Al obtener los tokens de forma automática, la aplicación puede recibir errores si una API a la que está intentando acceder requiere un desafío de notificaciones de acceso condicional como, por ejemplo, una directiva de autenticación multifactor.

El patrón para controlar este error consiste en adquirir interactivamente un token mediante MSAL. De esta forma, se avisa al usuario y le da la oportunidad de cumplir con la directiva de acceso condicional requerida.

En algunos casos, al llamar a una API que requiere acceso condicional, puede recibir un desafío de notificaciones en el error de la API. Por ejemplo, si la directiva de acceso condicional consiste en tener un dispositivo administrado (Intune) el error puede ser parecido a este: AADSTS53000: Your device is required to be managed to access this resource (Se requiere que su dispositivo sea administrado para acceder a este recurso) o algo parecido. En este caso, puede pasar las notificaciones de la llamada de adquisición del token de manera que se le pida al usuario que cumpla con la directiva adecuada.

Al obtener los tokens de forma automática (mediante acquireTokenSilent) con MSAL.js, la aplicación puede recibir errores cuando una API a la que está intentando acceder requiere un desafío de notificaciones de acceso condicional como, por ejemplo, una directiva de MFA.

El patrón para controlar este error consiste en realizar una llamada interactiva para adquirir el token en MSAL.js como, por ejemplo, acquireTokenPopup o acquireTokenRedirect como se puede ver en el ejemplo siguiente:

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);
        });
    }
});

La adquisición interactiva del token avisa al usuario y le da la oportunidad de cumplir con la directiva de acceso condicional requerida.

Al llamar a una API que requiere acceso condicional, puede recibir un desafío de notificaciones en el error de la API. En este caso, puede pasar las notificaciones devueltas en el error al parámetro claims del objeto de solicitud de token de acceso para satisfacer la política adecuada.

Consulte Uso de las API habilitadas para la evaluación continua de acceso en las aplicaciones para obtener más información.

Uso de otros marcos

El uso de kits de herramientas como Tauri para aplicaciones de página única (SPA) registradas con la plataforma de identidad no se reconoce para aplicaciones de producción. Las SPA solo admiten direcciones URL que comienzan por https para las aplicaciones de producción y http://localhost para el desarrollo local. Los prefijos como tauri://localhost no se pueden usar para las aplicaciones del explorador. Este formato solo se puede admitir para aplicaciones móviles o web, ya que tienen un componente confidencial, a diferencia de las aplicaciones del explorador.

Nuevos intentos después de errores y excepciones

Se espera que implemente sus propias directivas de reintentos al llamar a MSAL. MSAL realiza llamadas HTTP al servicio de Microsoft Entra y, en ocasiones, pueden producirse errores. Por ejemplo, la red puede dejar de funcionar o el servidor sobrecargarse.

HTTP 429

Cuando el servidor de token de servicio (STS) se sobrecarga con demasiadas solicitudes, devuelve un error HTTP 429 con una sugerencia sobre el tiempo de espera necesario antes de volver a intentarlo en el campo de respuesta Retry-After.

Pasos siguientes

Considere la posibilidad de habilitar el registro en MSAL.js como ayuda para diagnosticar y depurar problemas