Поделиться через

Обработка ошибок и исключений в MSAL.js

  • Статья

В этой статье приводятся общие сведения о различных типах ошибок и рекомендации по обработке распространенных ошибок входа.

Основные сведения об обработке ошибок MSAL

В библиотеке проверки подлинности Майкрософт (MSAL) применяются исключения, которые позволяют разработчикам приложений устранять проблемы самостоятельно, не отображая сообщения об ошибках пользователям. Сообщения об исключениях не локализованы.

При обработке ошибок и исключений вы можете различать их по типам исключений и кодам ошибки. Список кодов ошибок см. в разделе "Проверка подлинности Microsoft Entra" и коды ошибок авторизации.

Во время входа в систему могут происходить ошибки, связанные с согласованностью, условным доступом (MFA, управлением устройствами, ограничениями на основе расположения), выдачей и возвратом токенов и свойствами пользователей.

В следующем разделе приведены дополнительные сведения об обработке ошибок для приложения.

Обработка ошибок в MSAL.js

MSAL.js предоставляет объекты ошибок, которые являются абстрактными и используются для классификации различных типов распространенных ошибок. Эта библиотека также предоставляет интерфейс для доступа к конкретным сведениям об ошибках, например сообщениям об ошибках, что позволяет правильно их обрабатывать.

Объект ошибки

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

Расширяя класс Error, вы получаете доступ к следующим свойствам.

  • AuthError.message: эквивалентно errorMessage.
  • AuthError.stack: стек трассировки для возникновения ошибок.

Типы ошибок

Ниже приведены доступные типы ошибок.

  • AuthError: базовый класс ошибок для библиотеки MSAL.js также используется для непредвиденных ошибок.

  • ClientAuthError: класс ошибок, обозначающий проблему с проверкой подлинности клиента. Большинство ошибок, поступающих из библиотеки, — ClientAuthErrors. Эти ошибки происходят из-за вызова метода входа, когда вход уже выполняется, отмены входа пользователем и т. п.

  • ClientConfigurationError: класс ошибок, расширяющийся ClientAuthError. Он возникает перед выполнением запросов, когда заданные параметры конфигурации пользователя неправильно сформированы или отсутствуют.

  • ServerError: класс ошибок представляет строки ошибок, отправленные сервером проверки подлинности. Эти ошибки могут быть недопустимыми форматами запросов или параметрами, а также другими ошибками, которые препятствуют проверке подлинности сервера или авторизации пользователя.

  • InteractionRequiredAuthError: класс ошибок расширяется ServerError для представления ошибок сервера, для которых требуется интерактивный вызов. Такую ошибку вызывает acquireTokenSilent, если пользователю необходимо связаться с сервером и предоставить учетные данные или согласие для целей проверки подлинности и (или) авторизации. Коды ошибок: "interaction_required", "login_required" и "consent_required".

Для обработки ошибок в потоках проверки подлинности с методами перенаправления (loginRedirect, acquireTokenRedirect) необходимо обработать обещание перенаправления, которое вызывается с успехом или сбоем после перенаправления с помощью handleRedirectPromise() метода следующим образом:

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

Методы всплывающих возможностей (, acquireTokenPopup) возвращают обещания, поэтому можно использовать шаблон обещания (loginPopup.thenи.catch) для их обработки, как показано ниже.

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

Ошибки, требующие взаимодействия

Ошибка возвращается при попытке использовать неинтерактивный метод получения токена, например acquireTokenSilent, если MSAL не может получить его автоматически.

Возможны следующие причины:

  • требуется вход в систему;
  • требуется предоставить согласие;
  • нужно пройти многофакторную проверку подлинности.

Чтобы избавиться от этой ошибки, нужно вызывать интерактивный метод, например acquireTokenPopup или 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);
            });
    }
});

Условный доступ и запросы утверждений

Если вы получаете токены автоматически, приложение может получать ошибки, когда для используемого API применяются запросы утверждений условного доступа, например политики MFA.

Для обработки этой ошибки следует получить токен в интерактивном режиме с помощью MSAL. В результате пользователь получает запрос и возможность выполнить требования политики условного доступа.

В некоторых случаях при вызове API, требующих условного доступа, вы можете получать запрос утверждений прямо в полученной от API ошибке. Например, если политика условного доступа должна иметь управляемое устройство (Intune), ошибка будет примерно так же, как AADSTS53000: устройство должно быть управляемо для доступа к этому ресурсу или что-то подобное. В этом случае вы можете передать утверждения в запросе на получение токена, чтобы пользователь получил приглашение выполнить требования политики.

При автоматическом получении маркеров (acquireTokenSilentс помощью) с помощью MSAL.js приложение может получать ошибки, когда API, к которым вы пытаетесь получить доступ, требуется вызов утверждений условного доступа, например политика MFA.

Для обработки этой ошибки следует выполнить интерактивный вызов для получения токена через MSAL.js, например acquireTokenPopup или acquireTokenRedirect, как в следующем примере:

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

Интерактивное получение токена передает запрос пользователю и предоставляет ему возможность выполнить требования политики условного доступа.

При вызове API, требующих условного доступа, вы можете получать запрос утверждений прямо в полученной от API ошибке. В этом случае можно передать утверждения, возвращенные в ошибке claims параметру в объекте запроса маркера доступа, чтобы удовлетворить соответствующую политику.

Дополнительные сведения см. в статье об использовании API с поддержкой непрерывного доступа в приложениях .

Использование других платформ

Использование таких средств, как Tauri для зарегистрированных приложений с одной страницей (SPAs) с платформой удостоверений, не распознается для рабочих приложений. SpAs поддерживают только URL-адреса, начинающиеся с https рабочих приложений и http://localhost для локальной разработки. Префиксы, такие как tauri://localhost нельзя использовать для приложений браузера. Этот формат поддерживается только для мобильных или веб-приложений, так как они имеют конфиденциальный компонент в отличие от браузерных приложений.

Повторные попытки после ошибок и исключений

При вызове MSAL следует реализовать собственные политики повтора попытки. MSAL выполняет HTTP-вызовы в службу Microsoft Entra, и иногда могут возникать сбои. Например, в сети может произойти авария или сервер будет перегружен.

HTTP 429

Когда сервер токенов службы (STS) перегружен из-за слишком большого количества запросов, он возвращает ошибку HTTP 429 с указанием времени ожидания до следующей попытки в поле ответа Retry-After.

Следующие шаги

Рассмотрите возможность включения ведения журнала в MSAL.js для диагностики и отладки проблем