MSAL.js におけるエラーと例外の処理

  • [アーティクル]

この記事では、さまざまな種類のエラーの概要と、一般的なサインイン エラーを処理するための推奨事項を提供します。

MSAL のエラー処理の基本

Microsoft Authentication Library (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";
}

エラー クラスを拡張することで、次のプロパティにアクセスできます。

  • AuthError.message: errorMessage と同一です。
  • AuthError.stack:スローされたエラーのスタック トレースです。

エラーの種類

次のエラーの種類を使用できます。

  • AuthError:MSAL.js ライブラリの基本エラー クラス、予期しないエラーにも使用されます。

  • ClientAuthError: クライアント認証の問題を示すエラー クラス。 ライブラリから発生するほとんどのエラーは ClientAuthError です。 これらのエラーは、ログインが既に進行中のときにログイン メソッドを呼び出した場合、ユーザーがログインをキャンセルした場合などに発生します。

  • ClientConfigurationError: ClientAuthError を拡張するエラー クラス。 これは、指定されたユーザー設定パラメーターの形式が不正であるか欠落している場合、リクエストが行われる前にスローされます。

  • ServerError:認証サーバーによって送信されるエラー文字列を表すエラー クラス。 これらは、無効な要求形式やパラメーターなどのエラー、またはサーバーがユーザーを認証または承認できない他のエラーです。

  • InteractionRequiredAuthError:対話型の呼び出しを必要とするサーバー エラーを表す、ServerError を拡張するエラー クラス。 このエラーは、認証/承認に対する資格情報または同意を提供するためにユーザーがサーバーと対話する必要がある場合に、acquireTokenSilent によってスローされます。 エラーコードには、"interaction_required"、"login_required"、"consent_required" が含まれます。

リダイレクト メソッド (loginRedirect、acquireTokenRedirect) での認証フローにおけるエラー処理の場合、次のように、handleRedirectPromise() メソッドを使用するリダイレクトの後に成功または失敗で呼び出されるリダイレクト Promise を処理する必要があります。

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 が返されるので、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: Your device is required to be managed to access this resource (このリソースにアクセスするには、デバイスがマネージドである必要があります) のようなものになります。 この場合、トークン取得呼び出しでクレームを渡して、適切なポリシーを満たすようユーザーに求めることができます。

MSAL.js を使用してトークンをサイレントに (acquireTokenSilent を使用して) 取得する場合、アクセスしようとしている API に MFA ポリシーなどの条件付きアクセス クレーム チャレンジが必要な場合、アプリケーションでエラーが発生する可能性があります。

このエラーを処理するパターンは、次の例のように、acquireTokenPopup や acquireTokenRedirect など、MSAL.js でトークンを取得する対話型の呼び出しを行うことです。

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 をアプリケーションで使用する方法」をご覧ください。

他のフレームワークの使用

登録されたシングル ページ アプリケーション (SPA) に Tauri などのツールキットを ID プラットフォームと共に使用した場合、運用アプリでは認識されません。 SPA は、本番アプリでは https で始まる URL、ローカル開発では http://localhost で始まる URL のみをサポートします。 tauri://localhost のようなプレフィックスは、ブラウザー アプリには使用できません。 この形式は、ブラウザー アプリとは異なり機密コンポーネントがあるため、モバイル アプリまたは Web アプリのみでサポートできます。

エラーおよび例外の後の再試行

MSAL を呼び出すときには、独自の再試行ポリシーを実装することが求められます。 MSAL では Microsoft Entra サービスに対して HTTP 呼び出しが行われ、場合によってはエラーが発生することがあります。 たとえば、ネットワークがダウンしたり、サーバーが過負荷になったりする可能性があります。

HTTP 429

サービス トークン サーバー (STS) が過剰な要求で過負荷になると、HTTP エラー 429 が返され、Retry-After 応答フィールドで再試行できるまでの期間に関するヒントが示されます。

次のステップ

問題の診断とデバッグに役立つように、MSAL.js でログ記録を有効にすることを検討してください