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

Artykuł
12/19/2023

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 biblioteki 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 rozszerza ServerError się, aby reprezentować błędy serwera, które wymagają wywołania interakcyjnego. Ten błąd jest zgłaszany, acquireTokenSilent jeśli użytkownik jest wymagany do interakcji z serwerem w celu podania poświadczeń lub zgody 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 obietnicy (.then i .catch) do obsługi ich, 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 środowisko 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 dyskretnego pobierania tokenów aplikacja może otrzymywać błędy, gdy wyzwanie oświadczeń dostępu warunkowego, takie jak zasady uwierzytelniania wieloskładnikowego, jest wymagane przez interfejs API, do którego próbujesz uzyskać dostęp.

Wzorzec obsługi tego błędu polega na interakcyjnym uzyskiwaniu tokenu przy użyciu biblioteki MSAL. Spowoduje to wyświetlenie monitu użytkownika i umożliwienie mu spełnienia wymaganych zasad dostępu warunkowego.

W niektórych przypadkach podczas wywoływania interfejsu API wymagającego dostępu warunkowego możesz otrzymać wyzwanie dotyczące oświadczeń w błędzie z interfejsu API. Jeśli na przykład zasady dostępu warunkowego mają mieć zarządzane urządzenie (Intune), błąd będzie podobny do AADSTS53000: Urządzenie musi być zarządzane w celu uzyskania dostępu do tego zasobu lub podobnego. W takim przypadku można przekazać oświadczenia w wywołaniu tokenu uzyskiwania, aby użytkownik był monitowany o spełnienie odpowiednich zasad.

W przypadku dyskretnego uzyskiwania tokenów (przy użyciu programu ) przy użyciu acquireTokenSilentMSAL.js aplikacja może otrzymywać błędy, gdy interfejs API, do którego próbujesz uzyskać dostęp, wymaga żądania 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ć oświadczenia zwrócone w błędzie do claims parametru 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.

Ponów próbę po błędach i wyjątkach

Oczekuje się, że podczas wywoływania biblioteki MSAL należy zaimplementować 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 przez