Delen via

Fouten en uitzonderingen verwerken in MSAL.js

  • Artikel

Dit artikel bevat een overzicht van de verschillende typen fouten en aanbevelingen voor het afhandelen van veelvoorkomende aanmeldingsfouten.

Basisprincipes van MSAL-foutafhandeling

Uitzonderingen in Microsoft Authentication Library (MSAL) zijn bedoeld voor app-ontwikkelaars om problemen op te lossen, niet voor weergave aan eindgebruikers. Uitzonderingsberichten zijn niet gelokaliseerd.

Wanneer u uitzonderingen en fouten verwerkt, kunt u het uitzonderingstype zelf en de foutcode gebruiken om onderscheid te maken tussen uitzonderingen. Zie Microsoft Entra-verificatie- en autorisatiefoutcodes voor een lijst met foutcodes.

Tijdens de aanmeldingservaring kunnen fouten optreden over toestemmingen, voorwaardelijke toegang (MFA, apparaatbeheer, beperkingen op basis van locatie), tokenuitgifte en inwisseling en gebruikerseigenschappen.

In de volgende sectie vindt u meer informatie over foutafhandeling voor uw app.

Foutafhandeling in MSAL.js

MSAL.js biedt foutobjecten die de verschillende typen veelvoorkomende fouten abstraheren en classificeren. Het biedt ook een interface voor toegang tot specifieke details van de fouten, zoals foutberichten om ze op de juiste manier te verwerken.

Foutobject

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

Door de foutklasse uit te breiden, hebt u toegang tot de volgende eigenschappen:

  • AuthError.message: Hetzelfde als de errorMessage.
  • AuthError.stack: Stack-trace voor gegenereerde fouten.

Fouttypen

De volgende fouttypen zijn beschikbaar:

  • AuthError: Basisfoutklasse voor de MSAL.js-bibliotheek, ook gebruikt voor onverwachte fouten.

  • ClientAuthError: Foutklasse die een probleem met clientverificatie aangeeft. De meeste fouten die afkomstig zijn uit de bibliotheek zijn ClientAuthErrors. Deze fouten zijn het gevolg van zaken als het aanroepen van een aanmeldingsmethode wanneer de aanmelding al wordt uitgevoerd, de gebruiker annuleert de aanmelding, enzovoort.

  • ClientConfigurationError: Foutklasse die zich uitbreidt ClientAuthError. Deze wordt gegenereerd voordat aanvragen worden gedaan wanneer de opgegeven gebruikersconfiguratieparameters onjuist zijn of ontbreken.

  • ServerError: Foutklasse, vertegenwoordigt de foutreeksen die door de verificatieserver worden verzonden. Deze fouten kunnen ongeldige aanvraagindelingen of parameters zijn, of andere fouten die verhinderen dat de server de gebruiker kan verifiëren of autoriseren.

  • InteractionRequiredAuthError: Foutklasse, breidt zich uit ServerError om serverfouten weer te geven, waarvoor een interactieve aanroep is vereist. Deze fout treedt op als acquireTokenSilent de gebruiker moet communiceren met de server om referenties of toestemming voor verificatie/autorisatie op te geven. Foutcodes zijn onder andere "interaction_required", "login_required"en "consent_required".

Voor foutafhandeling in verificatiestromen met omleidingsmethoden (loginRedirect, acquireTokenRedirect), moet u de omleidingsbelofte afhandelen, die wordt aangeroepen met succes of mislukt na de omleiding met behulp van de handleRedirectPromise() methode als volgt:

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

De methoden voor pop-upervaring (loginPopup, acquireTokenPopup) retourneren beloftes, zodat u het promise-patroon (.then en .catch) kunt gebruiken om ze te verwerken zoals wordt weergegeven:

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

Fouten waarvoor interactie is vereist

Er wordt een fout geretourneerd wanneer u probeert een niet-interactieve methode te gebruiken voor het verkrijgen van een token, zoals acquireTokenSilent, maar MSAL kan dit niet op de achtergrond doen.

Mogelijke redenen zijn:

  • u moet zich aanmelden
  • u moet toestemming geven
  • u moet een multi-factor authentication-ervaring doorlopen.

Het herstel is het aanroepen van een interactieve methode zoalsacquireTokenPopup: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);
            });
    }
});

Problemen met voorwaardelijke toegang en claims

Wanneer tokens op de achtergrond worden opgehaald, kan uw toepassing fouten ontvangen wanneer een uitdaging voor claims voor voorwaardelijke toegang, zoals MFA-beleid, is vereist door een API die u probeert te openen.

Het patroon voor het afhandelen van deze fout is om interactief een token te verkrijgen met BEHULP van MSAL. Hiermee wordt de gebruiker gevraagd en krijgt deze de mogelijkheid om te voldoen aan het vereiste beleid voor voorwaardelijke toegang.

In bepaalde gevallen bij het aanroepen van een API waarvoor voorwaardelijke toegang is vereist, kunt u een claimvraag ontvangen in de fout van de API. Als het beleid voor voorwaardelijke toegang bijvoorbeeld een beheerd apparaat (Intune) heeft, wordt de fout ongeveer AADSTS53000 : uw apparaat moet worden beheerd om toegang te krijgen tot deze resource of iets dergelijks. In dit geval kunt u de claims doorgeven in de aanroep van het acquire-token, zodat de gebruiker wordt gevraagd om te voldoen aan het juiste beleid.

Wanneer tokens op de achtergrond worden opgehaald (met behulp van acquireTokenSilentMSAL.js), kan uw toepassing fouten krijgen wanneer de API die u probeert te openen, een uitdaging voor voorwaardelijke toegang vereist, zoals MFA-beleid.

Het patroon voor het afhandelen van deze fout is het maken van een interactieve aanroep om een token te verkrijgen in MSAL.js, zoals acquireTokenPopup in acquireTokenRedirect het volgende voorbeeld:

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

Interactief het ophalen van het token vraagt de gebruiker en geeft deze de mogelijkheid om te voldoen aan het vereiste beleid voor voorwaardelijke toegang.

Wanneer u een API aanroept waarvoor voorwaardelijke toegang is vereist, kunt u een claimvraag ontvangen in de fout van de API. In dit geval kunt u de claims die in de fout worden geretourneerd, doorgeven aan de claims parameter in het toegangstokenaanvraagobject om te voldoen aan het juiste beleid.

Zie Continue toegangsevaluatie-API's gebruiken in uw toepassingen voor meer informatie.

Andere frameworks gebruiken

Het gebruik van toolkits zoals Tauri voor geregistreerde toepassingen met één pagina (SPA's) met het identiteitsplatform wordt niet herkend voor productie-apps. SPA's ondersteunen alleen URL's die beginnen met https productie-apps en http://localhost voor lokale ontwikkeling. Voorvoegsels zoals tauri://localhost kunnen niet worden gebruikt voor browser-apps. Deze indeling kan alleen worden ondersteund voor mobiele apps of web-apps omdat ze een vertrouwelijk onderdeel hebben in tegenstelling tot browser-apps.

Opnieuw proberen na fouten en uitzonderingen

U wordt verwacht dat u uw eigen beleid voor opnieuw proberen implementeert bij het aanroepen van MSAL. MSAL maakt HTTP-aanroepen naar de Microsoft Entra-service en soms kunnen er fouten optreden. Het netwerk kan bijvoorbeeld uitvalt of de server overbelast is.

HTTP 429

Wanneer de Service Token Server (STS) overbelast is met te veel aanvragen, retourneert deze HTTP-fout 429 met een hint over hoe lang het duurt voordat u het opnieuw kunt proberen in het Retry-After antwoordveld.

Volgende stappen

Overweeg logboekregistratie in te schakelen in MSAL.js om u te helpen bij het vaststellen en opsporen van problemen