處理 MSAL.js 中的錯誤和例外狀況

發行項
07/02/2024

本文概述不同類型的錯誤，以及用於處理常見登入錯誤的建議。

MSAL 錯誤處理基本概念

Microsoft 驗證程式庫 (MSAL) 中的例外狀況僅供應用程式開發人員進行疑難排解之用，而不會向終端使用者顯示。例外狀況訊息不會當地語系化。

在處理例外狀況和錯誤時，您可以使用例外狀況類型本身和錯誤碼來區別例外狀況。如需錯誤碼清單，請參閱 Microsoft Entra 驗證與授權錯誤碼。

在登入體驗期間，您可能會遇到關於同意、條件式存取 (MFA、裝置管理、位置型限制)、權杖發行和兌換，以及使用者屬性的錯誤。

下一節提供有關應用程式錯誤處理的詳細資料。

MSAL.js 中的錯誤處理

MSAL.js 會提供錯誤物件，以摘要和分類不同類型的常見錯誤。其也會提供介面來存取錯誤的特定詳細資料，例如可供適當處理錯誤的錯誤訊息。

Error 物件

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

藉由擴充錯誤類別，您將可存取下列屬性：

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

快顯體驗的方法 (loginPopup、acquireTokenPopup) 會傳回承諾，因此您可以使用承諾模式 (.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：您的裝置必須受管理才能存取此資源或之類的內容。在此情況下，您可以在取得權杖的呼叫中傳入宣告，讓系統提示使用者符合適當的原則。

使用 MSAL.js 以無訊息模式取得權杖時 (使用 acquireTokenSilent)，若嘗試存取的 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 之類的工具組搭配身分識別平台來註冊單頁應用程式 (SPA)，並不被視為實際執行環境的應用程式。 SPA 僅支援以 https 開始的 URL (用於實際執行環境的 App)，以及以 http://localhost 開始的 URL (用於本機開發)。 tauri://localhost 之類的前置詞無法用於瀏覽器應用程式。只有行動或 Web 應用程式有與瀏覽器應用程式不同的機密元件，才能支援此格式。

在發生錯誤和例外狀況後重試

在呼叫 MSAL 時，您應該要實作自己的重試原則。 MSAL 會對 Microsoft Entra 服務發出 HTTP 呼叫，有時可能會失敗。例如，網路可能會中斷，或伺服器超載。

HTTP 429

服務權杖伺服器 (STS) 因為要求太多而超載時，便會傳回 HTTP 錯誤 429，並提示您要等多久才能在 Retry-After 回應欄位中再試一次。

下一步

請考量啟用 MSAL.js 中的記錄功能，以協助診斷和偵錯問題

共用方式為