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

發行項
03/14/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：Error 類別，代表驗證伺服器所傳送的錯誤字串。這些錯誤可能是無效的要求格式或參數，或防止伺服器驗證或授權使用者的任何其他錯誤。
InteractionRequiredAuthError：錯誤類別，擴充 ServerError 為表示需要互動式呼叫的伺服器錯誤。如果使用者需要與伺服器互動以提供驗證/授權的認證或同意，就會擲回 acquireTokenSilent 此錯誤。錯誤碼包括 "interaction_required"、 "login_required"與 "consent_required"。

若要使用重新導向方法處理驗證流程中的錯誤處理，loginRedirectacquireTokenRedirect您必須處理重新導向承諾，使用方法在重新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）會傳回承諾，因此您可以使用 Promise 模式（.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，以及 http://localhost 用於本機開發。之類的 tauri://localhost 前置詞無法用於瀏覽器應用程式。只有行動或 Web 應用程式有與瀏覽器應用程式不同的機密元件，才能支援此格式。

在錯誤和例外狀況之後重試

您應該會在呼叫 MSAL 時實作自己的重試原則。 MSAL 對 Microsoft Entra 服務進行 HTTP 呼叫，而且偶爾會發生失敗。例如，網路可以關閉或伺服器多載。

HTTP 429

當服務令牌伺服器（STS）多載要求太多時，它會傳回 HTTP 錯誤 429，並提示在回應字段中再試一次 Retry-After 的時間。

下一步

請考慮啟用登入MSAL.js ，以協助您診斷和偵錯問題

共用方式為