Behandeln von Fehlern und Ausnahmen in MSAL.js

Dieser Artikel gibt einen Überblick über die verschiedenen Fehlerarten und Empfehlungen zur Behandlung von allgemeinen Anmeldefehlern.

Grundlagen der MSAL-Fehlerbehandlung

Ausnahmen in der Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL) sind für App-Entwickler vorgesehen, die eine Problembehandlung durchführen, und nicht für Endbenutzer. Ausnahmemeldungen sind nicht lokalisiert.

Bei der Verarbeitung von Ausnahmen und Fehlern können Sie den Ausnahmetyp selbst und den Fehlercode verwenden, um zwischen Ausnahmen zu unterscheiden. Eine Liste der Fehlercodes finden Sie unter Microsoft Entra-Authentifizierungs- und Autorisierungsfehlercodes.

Während der Anmeldung treten möglicherweise Fehler bei Zustimmungen, bedingtem Zugriff (MFA, Geräteverwaltung, standortbezogene Einschränkungen), Tokenausstellung und -einlösung sowie Benutzereigenschaften auf.

Im folgenden Abschnitt werden weitere Details zur Fehlerbehandlung für Ihre App erläutert.

Fehlerbehandlung in MSAL.js

MSAL.js stellt Fehlerobjekte bereit, mit denen die unterschiedlichen Typen allgemeiner Fehler abstrahiert und klassifiziert werden. Außerdem bietet es eine Schnittstelle für den Zugriff auf bestimmte Fehlerdetails (z. B. Fehlermeldungen), damit Sie sie entsprechend behandeln können.

Error-Objekt

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

Durch die Erweiterung der Fehlerklasse haben Sie Zugriff auf die folgenden Eigenschaften:

• AuthError.message: Identisch mit errorMessage.
• AuthError.stack: Die Stapelüberwachung für ausgelöste Fehler.

Fehlertypen

Folgende Fehlertypen sind verfügbar:

• AuthError: Die grundlegende Fehlerklasse für die MSAL.js-Bibliothek. Sie wird auch für unerwartete Fehler verwendet.

• ClientAuthError: Fehlerklasse, die auf ein Problem mit der Clientauthentifizierung hinweist. Bei den meisten Fehlern, die von der Bibliothek gemeldet werden, handelt es sich um ClientAuthErrors. Diese Fehler resultieren z.B. aus dem Aufrufen einer Anmeldemethode, wenn die Anmeldung bereits ausgeführt wird, oder dem Abbrechen der Anmeldung durch den Benutzer.

• ClientConfigurationError: Fehlerklasse, die ClientAuthError erweitert. Wird ausgelöst, bevor Anforderungen ausgeführt werden, wenn die angegebenen Benutzerkonfigurationsparameter falsch formatiert oder nicht vorhanden sind.

• ServerError: Fehlerklasse, die die vom Authentifizierungsserver gesendeten Fehlerzeichenfolgen darstellt. Bei den Fehlern kann es sich um ungültige Anforderungsformate oder -parameter sowie um andere Fehler handeln, die den Server an der Authentifizierung oder Autorisierung des Benutzers bzw, der Benutzerin hindern.

• InteractionRequiredAuthError: Fehlerklasse, die ServerError erweitert und Serverfehler darstellt, die einen interaktiven Aufruf erfordern. Dieser Fehler wird durch acquireTokenSilent ausgelöst, wenn der Benutzer mit dem Server interagieren muss, um Anmeldeinformationen anzugeben oder der Authentifizierung/Autorisierung zuzustimmen. Zu den Fehlercodes zählen "interaction_required", "login_required" und "consent_required".

Zur Fehlerbehandlung in Authentifizierungsflows mit Umleitungsmethoden (loginRedirect, acquireTokenRedirect) müssen Sie die Umleitungszusage, der nach der Umleitung erfolgreich oder mit einem Fehler aufgerufen wird, mithilfe der handleRedirectPromise()-Methode wie folgt verarbeiten:

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

Die Methoden für Popupfunktionen (loginPopup, acquireTokenPopup) geben Zusagen zurück. Auf diese Weise können Sie das Zusagemuster (.then und .catch) verwenden, um die Methoden zu behandeln, wie im Folgenden dargestellt:

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

Fehler, für die eine Interaktion erforderlich ist

Ein Fehler wird zurückgegeben, wenn Sie versuchen, eine nicht interaktive Methode (z.B. acquireTokenSilent) für den Tokenabruf zu verwenden, MSAL das Token aber nicht automatisch abrufen konnte.

Mögliche Gründe:

• Sie müssen sich anmelden.
• Sie müssen Ihre Zustimmung geben.
• Sie müssen eine mehrstufige Authentifizierung ausführen.

Die Lösung besteht darin, eine interaktive Methode wie acquireTokenPopup oder acquireTokenRedirect aufzurufen:

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

Bedingter Zugriff und Anspruchsaufforderungen

Beim automatischen Abruf von Token kann Ihre Anwendung Fehler empfangen, wenn für eine API, auf die Sie zugreifen möchten, eine Anspruchsaufforderung für bedingten Zugriff, wie z. B. eine MFA-Richtlinie, erforderlich ist.

Sie behandeln diesen Fehler in der Regel dadurch, dass Sie mithilfe von MSAL ein Token interaktiv abrufen. Der Benutzer erhält in Form einer Aufforderung die Möglichkeit, die erforderliche Richtlinie für bedingten Zugriff zu erfüllen.

In bestimmten Fällen können Sie beim Aufruf einer API, die bedingten Zugriff erfordert, in dem von der API ausgegebenen Fehler eine Anspruchsaufforderung erhalten. Wenn die Richtlinie für bedingten Zugriff beispielsweise ein verwaltetes Gerät (Intune) vorsieht, könnte eine mit der folgenden vergleichbare Fehlermeldung ausgegeben werden – AADSTS53000: Für den Zugriff auf diese Ressource müssen Sie ein verwaltetes Gerät verwenden. In diesem Fall können Sie die Ansprüche im Aufruf für den Tokenabruf übergeben, damit der Benutzer aufgefordert wird, die entsprechende Richtlinie zu erfüllen.

Beim automatischen Abruf von Token mit MSAL.js (und acquireTokenSilent) kann Ihre Anwendung Fehlermeldungen empfangen, wenn für die API, auf die Sie zuzugreifen versuchen, eine Anspruchsaufforderung für bedingten Zugriff, wie z. B. eine MFA-Richtlinie, erforderlich ist.

Sie behandeln diesen Fehler in der Regel dadurch, dass Sie einen interaktiven Aufruf ausführen, um ein Token in MSAL.js abzurufen, z. B. mit acquireTokenPopup oder acquireTokenRedirect. Siehe folgendes Beispiel:

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

Beim interaktiven Abruf des Tokens erhält der Benutzer in Form einer Aufforderung die Möglichkeit, die erforderliche Richtlinie für bedingten Zugriff zu erfüllen.

Beim Aufruf einer API, die bedingten Zugriff erfordert, können Sie in dem von der API ausgegebenen Fehler eine Anspruchsaufforderung erhalten. In diesem Fall können Sie die im Fehler zurückgegebenen Ansprüche an den claims-Parameter im Anforderungsobjekt des Zugriffstokens übergeben, um die entsprechende Richtlinie zu erfüllen.

Weitere Informationen finden Sie unter Verwenden von APIs mit aktivierter fortlaufender Zugriffsevaluierung in Ihren Anwendungen.

Verwenden anderer Frameworks

Die Verwendung von Toolkits wie Tauri für registrierte Single Page-Webanwendungen (SPAs) mit der Identitätsplattform wird für Produktions-Apps nicht anerkannt. SPAs unterstützen nur URLs, die mit https für Produktions-Apps oder http://localhost für die lokale Entwicklung beginnen. Präfixe wie tauri://localhost können für Browser-Apps nicht verwendet werden. Dieses Format kann nur für mobile Apps oder Web-Apps unterstützt werden, da sie im Gegensatz zu Browser-Apps über eine vertrauliche Komponente verfügen.

Wiederholung nach Fehlern und Ausnahmen

Es wird erwartet, dass Sie beim Aufrufen von MSAL eigene Wiederholungsrichtlinien implementieren. Von MSAL werden HTTP-Aufrufe an den Microsoft Entra-Dienst gerichtet. Hierbei können gelegentlich Fehler auftreten. So kann es beispielsweise zu einem Netzwerkausfall oder zu einer Überlastung des Servers kommen.

HTTP 429

Wenn der Diensttokenserver (Service Token Server, STS) durch zu viele Anforderungen überlastet ist, gibt er den HTTP-Fehler 429 mit einem Hinweis im Retry-After-Antwortfeld zu dem Zeitpunkt zurück, an dem Sie den Vorgang wiederholen können.

Nächste Schritte

Erwägen Sie die Aktivierung der Protokollierung in MSAL.js, um Probleme besser diagnostizieren und debuggen zu können