Control de errores y excepciones en MSAL.js

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

Aspectos básicos del control de errores de MSAL

Las excepciones de Biblioteca de autenticación de Microsoft (MSAL) están diseñadas para que los desarrolladores de aplicaciones solucionen problemas, no para mostrarlos a los usuarios finales. Los mensajes de excepción no se localizan.

Al procesar excepciones y errores, puede usar el propio tipo de excepción y el código de error para distinguir entre excepciones. Para obtener una lista de códigos de error, consulte Microsoft Entra códigos de error de autenticación y autorización.

Durante la experiencia de inicio de sesión, puede encontrar errores sobre los consentimientos, el acceso condicional (MFA, Administración de dispositivos, restricciones basadas en ubicación), la emisión y el canje de tokens y 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 correctamente.

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

Al extender la clase de error, tiene acceso a las siguientes propiedades:

• AuthError.message: igual que .errorMessage
• AuthError.stack: Rastreo de pila para los errores lanzados.

Tipos de error

Los siguientes tipos de error están disponibles:

• AuthError: clase de error base para la biblioteca de MSAL.js, que también se usa para 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 ClientAuthErrors. Estos errores resultan de cosas como llamar a un método de inicio de sesión cuando el inicio de sesión ya está en curso, el usuario cancela el inicio de sesión, etc.

• ClientConfigurationError: clase de error que extiende ClientAuthError y que se lanza antes de que se realicen solicitudes cuando los parámetros de configuración del usuario proporcionados tienen un formato incorrecto o faltan.

• ServerError: la clase de error representa las cadenas de error enviadas por el servidor de autenticación. Estos errores pueden ser formatos o parámetros de solicitud no válidos, o cualquier otro error que impida que el servidor autentique o autorice al usuario.

• InteractionRequiredAuthError: clase de error, se extiende ServerError para representar errores de servidor, que requieren una llamada interactiva. Este error se produce acquireTokenSilent si se requiere que el usuario 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 para la experiencia emergente (loginPopup, acquireTokenPopup) devuelven promesas, por lo que puede usar el patrón de promesa (.then y .catch) para controlarlos como se muestra:

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 como acquireTokenSilent, pero MSAL no pudo hacerlo de forma silenciosa.

Los posibles motivos son:

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

La correcció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);
            });
    }
});

Desafíos del acceso condicional y las reclamaciones

Al obtener los tokens de forma automática, la aplicación puede recibir errores si una API a la que intenta 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 es adquirir de forma interactiva 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 es tener un dispositivo administrado (Intune), el error será similar a AADSTS53000: el dispositivo debe administrarse para acceder a este recurso o algo similar. 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 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 es realizar una llamada interactiva para adquirir el token en MSAL.js como acquireTokenPopup o acquireTokenRedirect como 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 solicita la intervención del usuario y le da la oportunidad de cumplir 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 empiecen por https 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.

Reintentar 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 Microsoft Entra y, en ocasiones, se pueden producir errores. Por ejemplo, la red puede bajar o el servidor está sobrecargado.

HTTP 429

Cuando el servidor de token de servicio (STS) está sobrecargado con demasiadas solicitudes, devuelve el error HTTP 429 con una sugerencia sobre cuánto tiempo hasta que pueda volver a intentarlo en el campo de respuesta de Retry-After.

Pasos siguientes

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