Partager via

Gérer les erreurs et les exceptions dans MSAL.js

  • Article

Cet article donne une vue d’ensemble des différents types d’erreurs et des recommandations pour la gestion des erreurs de connexion courantes.

Notions de base de la gestion des erreurs MSAL

Dans Microsoft Authentication Library (MSAL), les exceptions sont destinées aux développeurs d’applications à des fins de résolution de problèmes. Elles n’ont pas vocation à être vues par les utilisateurs finaux. Les messages liés aux exceptions ne sont pas localisés.

Quand vous traitez les exceptions et les erreurs, vous pouvez utiliser le type d’exception lui-même et le code d’erreur pour les distinguer. Pour obtenir la liste des codes d’erreur, consultez Codes d’erreur d’authentification et d’autorisation Microsoft Entra.

Durant la connexion, vous pouvez rencontrer des erreurs concernant les consentements, l’accès conditionnel (MFA, gestion des appareils, restrictions basées sur l’emplacement), l’émission et l’échange de jetons, et les propriétés utilisateur.

La section suivante fournit plus d’informations sur la gestion des erreurs pour votre application.

Gestion des erreurs dans MSAL.js

MSAL.js fournit des objets d’erreur qui résument et classifient les différents types d’erreurs courantes. Il fournit également une interface permettant d’accéder à des détails spécifiques des erreurs, comme les messages d’erreur, afin de les traiter de manière appropriée.

Objet d’erreur

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

En étendant la classe d’erreur, vous avez accès aux propriétés suivantes :

  • AuthError.message : Identique à errorMessage.
  • AuthError.stack: Trace des erreurs levées.

Types d’erreurs

Les types d’erreur suivants sont disponibles :

  • AuthError: Classe d’erreur de base pour la bibliothèque MSAL.js, également utilisée pour les erreurs inattendues.

  • ClientAuthError : classe d’erreur qui indique un problème avec l’authentification du client. La plupart des erreurs provenant de la bibliothèque sont de type ClientAuthError. Ces erreurs proviennent de l’appel d’une méthode de connexion lorsque la connexion est déjà en cours, que l’utilisateur annule la connexion, et ainsi de suite.

  • ClientConfigurationError : classe d’erreur qui s’étend ClientAuthError. Il est lancé avant que les demandes ne soient effectuées quand les paramètres de configuration utilisateur donnés sont malformés ou manquants.

  • ServerError: Classe d’erreur représentant les chaînes d’erreur envoyées par le serveur d’authentification. Ces erreurs peuvent être des formats ou paramètres de requête non valides, ou encore d’autres erreurs qui empêchent le serveur d’authentifier ou d’autoriser l’utilisateur.

  • InteractionRequiredAuthError: Classe d’erreur qui étend une erreur de type ServerError permettant de représenter les erreurs de serveur qui exigent un appel interactif. Ce type d’erreur est levé par acquireTokenSilent si l’utilisateur est obligé d’interagir avec le serveur pour fournir des informations d’identification ou donner son consentement à l’authentification/autorisation. Les codes d’erreur sont les suivants : "interaction_required", "login_required" et "consent_required".

Pour gérer les erreurs dans les flux d’authentification avec des méthodes de redirection (loginRedirect, acquireTokenRedirect), vous devrez traiter la promesse de redirection qui est appelée avec ou sans succès après la redirection avec la méthode handleRedirectPromise() comme suit :

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

Les méthodes liées à une expérience contextuelle (loginPopup, acquireTokenPopup) retournent des promesses, donc vous pouvez utiliser le modèle de promesse (.then et .catch) pour les gérer comme indiqué :

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

Erreurs qui nécessitent une interaction

Une erreur est retournée lorsque vous essayez d’utiliser une méthode non interactive pour acquérir un jeton, tel que acquireTokenSilent, mais que MSAL ne peut pas le faire en mode silencieux.

Les raisons possibles sont :

  • Vous devez vous connecter.
  • Vous devez donner votre consentement.
  • Vous devez passer par une expérience d’authentification multifacteur.

Pour corriger cette erreur, appelez une méthode interactive comme 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);
            });
    }
});

Accès conditionnel et revendications

Quand vous obtenez des jetons silencieusement, votre application risque de recevoir des erreurs quand une revendication d’accès conditionnel, comme une stratégie d’authentification multifacteur, est exigée par une API à laquelle vous essayez d’accéder.

Le modèle de gestion de cette erreur consiste à acquérir de manière interactive un jeton à l’aide de MSAL. Cela adresse une invite à l’utilisateur et lui donne la possibilité de satisfaire à la stratégie d’accès conditionnel exigée.

Dans certains cas, lors de l’appel d’une API qui exige un accès conditionnel, vous pouvez recevoir une revendication dans l’erreur de la part de l’API. Par exemple, si la stratégie d’accès conditionnel consiste à utiliser un appareil managé (Intune), l’erreur est de type AADSTS53000 : Votre appareil doit être managé pour accéder à cette ressource ou quelque chose de semblable. Dans ce cas, vous pouvez transmettre la revendication dans l’appel d’acquisition du jeton, afin que l’utilisateur soit invité à satisfaire à la stratégie appropriée.

Quand vous obtenez des jetons silencieusement (en utilisant acquireTokenSilent) avec MSAL.js, votre application risque de recevoir des erreurs quand une revendication d’accès conditionnel comme une stratégie d’authentification multifacteur est exigée par une API à laquelle vous essayez d’accéder.

Le modèle permettant de gérer cette erreur consiste à effectuer un appel interactif pour acquérir un jeton dans MSAL.js comme acquireTokenPopup ou acquireTokenRedirect, comme dans l’exemple suivant :

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

L’acquisition interactive du jeton propose une invite à l’utilisateur et lui donne la possibilité de satisfaire à la stratégie d’accès conditionnel exigée.

Lors de l’appel d’une API qui exige un accès conditionnel, vous pouvez recevoir une revendication dans l’erreur de la part de l’API. Dans ce cas, vous pouvez passer les revendications retournées dans l’erreur du paramètre claims dans l’objet de requête de jeton d’accès pour satisfaire la stratégie appropriée.

Consultez Guide pratique pour utiliser les API d’Évaluation continue de l’accès dans vos applications pour plus d’informations.

Utilisation d’autres infrastructures

L’utilisation de kit de ressource tels que Tauri pour les applications monopage (SPA) inscrites avec la plateforme d’identités n’est pas reconnue pour les applications de production. Les SPA prennent uniquement en charge les URL qui commencent par https pour les applications de production et http://localhost pour le développement local. Les préfixes tels que tauri://localhost ne peuvent pas être utilisés pour les applications de navigateur. Ce format ne peut être pris en charge que pour les applications mobiles ou web, car elles ont un composant confidentiel contrairement aux applications de navigateur.

Nouvelle tentative après des erreurs et exceptions

Vous êtes censé implémenter vos propres stratégies de nouvelle tentative lors de l’appel de MSAL. MSAL effectue des appels HTTP en direction du service Microsoft Entra. Des échecs peuvent parfois se produire. Par exemple, le réseau peut tomber en panne ou le serveur peut être surchargé.

HTTP 429

Lorsque le serveur de jeton de service (STS) est surchargé avec un trop grand nombre de requêtes, il renvoie une erreur HTTP 429 en indiquant, dans le champ de réponse Retry-After, la durée qui s’écoule avant que vous puissiez renouveler votre demande.

Étapes suivantes

Envisagez l’activation de la Journalisation dans MSAL.js pour vous aider à diagnostiquer et à déboguer les problèmes