Hantera fel och undantag i MSAL.js

2023-12-19

Den här artikeln ger en översikt över de olika typerna av fel och rekommendationer för hantering av vanliga inloggningsfel.

Grunderna för MSAL-felhantering

Undantag i Microsoft Authentication Library (MSAL) är avsedda för apputvecklare att felsöka, inte för att visas för slutanvändare. Undantagsmeddelanden är inte lokaliserade.

När du bearbetar undantag och fel kan du använda själva undantagstypen och felkoden för att skilja mellan undantag. En lista över felkoder finns i Felkoder för Microsoft Entra-autentisering och auktorisering.

Under inloggningen kan det uppstå fel om medgivanden, villkorsstyrd åtkomst (MFA, Enhetshantering, platsbaserade begränsningar), tokenutfärdande och inlösen samt användaregenskaper.

Följande avsnitt innehåller mer information om felhantering för din app.

Felhantering i MSAL.js

MSAL.js innehåller felobjekt som abstraherar och klassificerar de olika typerna av vanliga fel. Det ger också ett gränssnitt för att komma åt specifik information om felen, till exempel felmeddelanden för att hantera dem på rätt sätt.

Felobjekt

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

Genom att utöka felklassen har du åtkomst till följande egenskaper:

AuthError.message: Samma som errorMessage.
AuthError.stack: Stackspårning för kastade fel.

Feltyper

Följande feltyper är tillgängliga:

AuthError: Basfelklass för MSAL.js-biblioteket, som också används för oväntade fel.
ClientAuthError: Felklass som anger ett problem med klientautentisering. De flesta fel som kommer från biblioteket är ClientAuthErrors. Dessa fel beror på saker som att anropa en inloggningsmetod när inloggningen redan pågår, användaren avbryter inloggningen och så vidare.
ClientConfigurationError: Felklass som utökar ClientAuthError. Det utlöses innan begäranden görs när de angivna användarkonfigurationsparametrarna är felaktiga eller saknas.
ServerError: Felklass, representerar de felsträngar som skickas av autentiseringsservern. Dessa fel kan vara ogiltiga begärandeformat eller parametrar, eller andra fel som hindrar servern från att autentisera eller auktorisera användaren.
InteractionRequiredAuthError: Felklass, utökas ServerError för att representera serverfel, vilket kräver ett interaktivt anrop. Det här felet utlöses av acquireTokenSilent om användaren måste interagera med servern för att ange autentiseringsuppgifter eller medgivande för autentisering/auktorisering. Felkoder inkluderar "interaction_required", "login_required"och "consent_required".

För felhantering i autentiseringsflöden med omdirigeringsmetoder (loginRedirect, acquireTokenRedirect) måste du hantera omdirigeringslöftet, som anropas med framgång eller fel efter omdirigeringen med hjälp av handleRedirectPromise() metoden enligt följande:

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

Metoderna för popup-upplevelse (loginPopup, acquireTokenPopup) returnerar löften, så att du kan använda löftesmönstret (.then och .catch) för att hantera dem enligt följande:

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

Fel som kräver interaktion

Ett fel returneras när du försöker använda en icke-interaktiv metod för att hämta en token, till exempel acquireTokenSilent, men MSAL kunde inte göra det tyst.

Möjliga orsaker är:

du måste logga in
du måste samtycka
du måste gå igenom en multifaktorautentiseringsupplevelse.

Reparationen är att anropa en interaktiv metod som acquireTokenPopup eller 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);
            });
    }
});

Utmaningar med villkorsstyrd åtkomst och autentiseringsutmaningar

När du hämtar token tyst kan ditt program få fel när en anspråksutmaning för villkorsstyrd åtkomst, till exempel MFA-princip, krävs av ett API som du försöker komma åt.

Mönstret för att hantera det här felet är att interaktivt hämta en token med hjälp av MSAL. Detta uppmanar användaren och ger dem möjlighet att uppfylla den nödvändiga principen för villkorsstyrd åtkomst.

I vissa fall när du anropar ett API som kräver villkorsstyrd åtkomst kan du få en utmaning om anspråk i API-felmeddelandet. Om principen för villkorsstyrd åtkomst till exempel ska ha en hanterad enhet (Intune) blir felet ungefär som AADSTS53000: Enheten måste hanteras för att få åtkomst till den här resursen eller något liknande. I det här fallet kan du skicka anspråken i anropet för att hämta token så att användaren uppmanas att uppfylla rätt princip.

När du hämtar token tyst (med hjälp av acquireTokenSilent) med hjälp av MSAL.js kan ditt program få fel när API:et som du försöker komma åt kräver en anspråksutmaning för villkorsstyrd åtkomst, till exempel MFA-princip.

Mönstret för att hantera det här felet är att göra ett interaktivt anrop för att hämta token i MSAL.js till exempel acquireTokenPopup eller acquireTokenRedirect som i följande exempel:

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

Interaktiv anskaffning av token uppmanar användaren och ger dem möjlighet att uppfylla den nödvändiga principen för villkorsstyrd åtkomst.

När du anropar ett API som kräver villkorlig åtkomst kan du få en anspråksutmaning i felet från API:et. I det här fallet kan du skicka anspråken som returnerats av felet till parametern claims i objektet för begäran om åtkomsttoken för att följa den relevanta policyn.

Mer information finns i Använda API:er för kontinuerlig åtkomstutvärdering i dina program .

Använda andra ramverk

Användning av verktyg som Tauri för registrerade ensidesprogram (SPA) med identitetsplattformen känns inte igen för produktionsappar. SPA:er stöder endast URL:er som börjar med https för produktionsappar och http://localhost för lokal utveckling. Prefix som tauri://localhost inte kan användas för webbläsarappar. Det här formatet kan bara stödjas för mobilappar eller webbappar eftersom de har en konfidentiell komponent till skillnad från webbläsarappar.

Försök igen efter fel och undantag

Du förväntas implementera dina egna återförsöksprinciper när du anropar MSAL. MSAL gör HTTP-anrop till Microsoft Entra-tjänsten och ibland kan fel uppstå. Nätverket kan till exempel gå ner eller så är servern överbelastad.

HTTP 429

När servicetokenservern (STS) är överbelastad med för många begäranden returneras HTTP-fel 429 med en ledtråd om hur lång tid tills du kan försöka igen i svarsfältet Retry-After .

Nästa steg

Överväg att aktivera loggning i MSAL.js som hjälper dig att diagnostisera och felsöka problem

Feedback

Var den här sidan till hjälp?