Obsługa błędów i wyjątków w bibliotece MSAL.js

Artykuł
2025-04-22

Ten artykuł zawiera omówienie różnych typów błędów i zaleceń dotyczących obsługi typowych błędów logowania.

Podstawy obsługi błędów w MSAL

Wyjątki w bibliotece Microsoft Authentication Library (MSAL) są przeznaczone dla deweloperów aplikacji do rozwiązywania problemów, a nie wyświetlania użytkownikom końcowym. Komunikaty o wyjątkach nie są zlokalizowane.

Podczas przetwarzania wyjątków i błędów można użyć samego typu wyjątku i kodu błędu, aby odróżnić wyjątki. Aby uzyskać listę kodów błędów, zobacz Kody błędów uwierzytelniania i autoryzacji firmy Microsoft.

Podczas logowania mogą wystąpić błędy dotyczące zgody, dostępu warunkowego (MFA, Zarządzanie urządzeniami, ograniczeń opartych na lokalizacji), wystawiania i realizacji tokenów oraz właściwości użytkownika.

Poniższa sekcja zawiera więcej szczegółowych informacji na temat obsługi błędów dla aplikacji.

Obsługa błędów w MSAL.js

MSAL.js zawiera obiekty błędów, które abstrakują i klasyfikują różne typy typowych błędów. Udostępnia również interfejs umożliwiający uzyskanie dostępu do szczegółowych informacji o błędach, takich jak komunikaty o błędach, aby odpowiednio je obsłużyć.

Błąd obiektu

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

Rozszerzając klasę błędów, masz dostęp do następujących właściwości:

AuthError.message: taki sam jak errorMessage.
AuthError.stack: Ślad stosu dla zgłoszonych błędów.

Typy błędów

Dostępne są następujące typy błędów:

AuthError: Podstawowa klasa błędów biblioteki MSAL.js używana również w przypadku nieoczekiwanych błędów.
ClientAuthError: klasa błędów, która oznacza problem z uwierzytelnianiem klienta. Większość błędów pochodzących z biblioteki to ClientAuthErrors. Te błędy wynikają z takich rzeczy, jak wywoływanie metody logowania, gdy logowanie jest już w toku, użytkownik anuluje logowanie itd.
ClientConfigurationError: Klasa błędu, która rozszerza klasę ClientAuthError. Jest zgłaszany przed wykonaniem żądań, gdy podane parametry konfiguracji użytkownika są źle sformułowane lub brakuje.
ServerError: Klasa błędu reprezentuje ciągi błędów wysyłane przez serwer uwierzytelniania. Te błędy mogą być nieprawidłowymi formatami żądań lub parametrami lub innymi błędami, które uniemożliwiają serwerowi uwierzytelnianie lub autoryzowanie użytkownika.
InteractionRequiredAuthError: Klasa błędu, która rozszerza ServerError w celu reprezentacji błędów serwera, które wymagają wywołania interaktywnego. Ten błąd jest zgłaszany przez acquireTokenSilent, jeśli użytkownik musi wejść w interakcję z serwerem, aby podać poświadczenia lub wyrazić zgodę na uwierzytelnianie/autoryzację. Kody błędów obejmują "interaction_required", "login_required"i "consent_required".

W przypadku obsługi błędów w przepływach uwierzytelniania przy użyciu metod przekierowania (loginRedirect, acquireTokenRedirect), należy obsłużyć obietnicę przekierowania, która jest wywoływana z powodzeniem lub niepowodzeniem po przekierowaniu przy użyciu handleRedirectPromise() metody w następujący sposób:

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

Metody obsługi wyskakujących okienek (loginPopup, acquireTokenPopup) zwracają obietnice, dzięki czemu można użyć wzorca obietnic (.then i .catch) do ich obsługi, jak pokazano:

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

Błędy wymagające interakcji

Podczas próby użycia nieinterakcyjnej metody uzyskiwania tokenu, takiego jak acquireTokenSilent, zwracany jest błąd, ale biblioteka MSAL nie mogła tego zrobić dyskretnie.

Możliwe przyczyny:

musisz się zalogować
musisz wyrazić zgodę
Musisz przejść przez proces uwierzytelniania wieloskładnikowego.

Korygowanie polega na wywołaniu metody interaktywnej, takiej jak acquireTokenPopup lub 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);
            });
    }
});

Wyzwania związane z dostępem warunkowym i oświadczeniami

W przypadku pobierania tokenów w sposób dyskretny aplikacja może napotkać błędy, gdy wymagane jest wyzwanie związane z dostępem warunkowym, na przykład zgodnie z polityką MFA, przez interfejs API, do którego próbujesz uzyskać dostęp.

Wzorzec obsługi tego błędu polega na interakcyjnym uzyskiwaniu tokenu z użyciem MSAL. Powoduje to, że użytkownik zostaje poproszony o spełnienie wymaganych zasad dostępu warunkowego.

W niektórych przypadkach podczas wywoływania interfejsu API wymagającego dostępu warunkowego możesz otrzymać wyzwanie związane z roszczeniami w błędzie z interfejsu API. Jeśli na przykład w polityce dostępu warunkowego wymagane jest zarządzanie urządzeniem (Intune), błąd może wyglądać na przykład tak: AADSTS53000: Urządzenie musi być zarządzane w celu uzyskania dostępu do tego zasobu lub podobnie. W takim przypadku można przekazać oświadczenia w wywołaniu pobierania tokenu, aby użytkownik był poproszony o spełnienie odpowiedniej polityki.

W przypadku dyskretnego uzyskiwania tokenów przy użyciu acquireTokenSilentMSAL.js, aplikacja może otrzymywać błędy, gdy interfejs API, do którego próbujesz uzyskać dostęp, wymaga wyzwania w zakresie oświadczeń dostępu warunkowego, takiego jak zasady uwierzytelniania wieloskładnikowego.

Wzorzec obsługi tego błędu polega na wykonaniu interakcyjnego wywołania w celu uzyskania tokenu w MSAL.js, takich jak acquireTokenPopup lub acquireTokenRedirect w poniższym przykładzie:

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

Interaktywne uzyskiwanie tokenu monituje użytkownika i daje im możliwość spełnienia wymaganych zasad dostępu warunkowego.

Podczas wywoływania interfejsu API wymagającego dostępu warunkowego możesz otrzymać wyzwanie dotyczące oświadczeń w błędzie z interfejsu API. W takim przypadku można przekazać roszczenia zwrócone w komunikacie o błędzie do parametru claims w obiekcie żądania tokenu dostępu, aby spełnić odpowiednie zasady.

Aby uzyskać więcej szczegółów, zobacz Jak używać interfejsów API z obsługą ciągłego dostępu w aplikacjach .

Korzystanie z innych struktur

Używanie zestawów narzędzi takich jak Tauri dla zarejestrowanych aplikacji jednostronicowych (SPA) z platformą tożsamości nie jest rozpoznawane w przypadku aplikacji produkcyjnych. Dostawcy usług obsługują tylko adresy URL rozpoczynające się od https aplikacji produkcyjnych i http://localhost programowania lokalnego. Prefiksy, takie jak tauri://localhost nie można używać w przypadku aplikacji przeglądarki. Ten format może być obsługiwany tylko w przypadku aplikacji mobilnych lub internetowych, ponieważ mają składnik poufny w przeciwieństwie do aplikacji przeglądarki.

Ponawianie prób po błędach i wyjątkach

Oczekuje się, że przy wywoływaniu MSAL zaimplementujesz własne zasady ponawiania prób. Biblioteka MSAL wykonuje wywołania HTTP do usługi Microsoft Entra, a czasami mogą wystąpić błędy. Na przykład sieć może spaść lub serwer jest przeciążony.

HTTP 429

Gdy serwer tokenów usługi (STS) jest przeciążony zbyt wieloma żądaniami, zwraca błąd HTTP 429 z wskazówką o tym, jak długo można spróbować ponownie w Retry-After polu odpowiedzi.

Następne kroki

Rozważ włączenie rejestrowania w MSAL.js , aby ułatwić diagnozowanie i debugowanie problemów

Udostępnij za pośrednictwem