MSAL Browser v4 から v5 への移行

MSAL を初めて使用する場合は、ここから始める必要があります。

MSAL v2 から来ている場合は、最初にこのガイドを確認して MSAL v3 に移行する必要があります。 MSAL v3 から来ている場合は、最初にこのガイドを確認して MSAL v4 に移行してから、次の手順に従う必要があります。

MSAL v4 から来ている場合は、このガイドに従って、MSAL v5 を使用するようにコードを更新できます。

API の破壊的変更

SignedHttpRequest.removeKeys 戻り値の型が変更されました

removeKeys クラスのSignedHttpRequest関数は、Promise<void>ではなくPromise<boolean>を返すようになりました。 Promise 正常な解決は、以前の true の戻り値に相当するようになりました。エラーが発生した場合、false を返す代わりにエラーとしてスローされるようになりました。

// BEFORE
const shr = new SignedHttpRequest(shrParameters, shrOptions);
const result = await shr.removeKeys(thumbprint);
if (result) {
    // do something on success
} else {
    // do something on failure
}

// AFTER
const shr = new SignedHttpRequest(shrParameters, shrOptions);
await shr
    .removeKeys(thumbprint)
    .then(() => {
        // do something on success
    })
    .catch((e) => {
        // do something on failure
        console.log(e);
    });

TokenCache と loadExternalTokens

loadExternalTokens の MSAL JS API が変更されました。それらの変更を次に示します。

TokenCache オブジェクトと getTokenCache() が削除されました
loadExternalTokens() API は別のエクスポートになり、パラメーターとしてConfigurationが必要になりました

// BEFORE

const pca = new PublicClientApplication(config);
await pca
    .getTokenCache()
    .loadExternalTokens(silentRequest, serverResponse, loadTokenOptions);

//AFTER

await loadExternalTokens(
    config,
    silentRequest,
    serverResponse,
    loadTokenOptions
);

`handleRedirectPromise` API シグネチャが変更されました

以前は、 PublicClientApplication.handleRedirectPromise 省略可能なハッシュパラメーターを使用しました。 HandleRedirectPromiseOptionsと呼ばれる新しいオプションの種類が導入されました。 MSAL Browser v5 の時点では、 HandleRedirectPromiseOptions 型の省略可能なオブジェクトが、 handleRedirectPromise() 受け入れる唯一のパラメーターです。

// BEFORE
const hash = window.location.hash; // Arbitrary example value
pca.handleRedirectPromise(hash);

// AFTER
pca.handleRedirectPromise({
    hash: window.location.hash, // Option nested inside a `HandleRedirectPromiseOptions` object
    navigateToLoginRequestUrl: true, // Additional option
});

`PublicClientApplication` の一部の機能の削除

PublicClientApplicationの次の関数は削除されました。

enableAccountStorageEvents() と disableAccountStorageEvents(): アカウントストレージイベントが常に有効になりました。これらの関数呼び出しは必要なくなりました。

getAccountByHomeId()、 getAccountByLocalId()、 getAccountByUsername(): 代わりに getAccount() を使用します。

// BEFORE
const account1 = accountManager.getAccountByHomeId(yourHomeAccountId);
const account2 = accountManager.getAccountByLocalId(yourLocalAccountId);
const account3 = accountManager.getAccountByUsername(yourUsername);

// AFTER
const account1 = accountManager.getAccount({
    homeAccountId: yourHomeAccountId,
});
const account2 = accountManager.getAccount({
    localAccountId: yourLocalAccountId,
});
const account3 = accountManager.getAccount({ username: yourUsername });

logout(): 代わりに logoutRedirect() または logoutPopup() を使用します。

`startPerformanceMeasurement()` の削除

startPerformanceMeasurement() は削除されました。代わりに、startMeasurement() を使用してください。

`PublicClientNext` の削除

PublicClientNext クラスとその静的メソッドcreatePublicClientApplication()は、MSAL v5 で削除されました。アプリケーションの要件に応じて、次のいずれかの代替手段を使用する必要があります。

PublicClientApplication: これは、標準のシングルアプリシナリオに使用します。これが既定で最も一般的な使用方法です。
createNestablePublicClientApplication: 入れ子になったアプリ (NAA) をサポートする必要がある場合に使用します。入れ子になったアプリブリッジが使用できない場合、または入れ子になったアプリ認証をサポートするようにハブが構成されていない場合、この関数は自動的に標準の PublicClientApplication にフォールバックします。詳細については、入れ子になったアプリの構成を参照してください。
createStandardPublicClientApplication: これを使用して、標準 (NAA 以外) の PublicClientApplication インスタンスをインスタンス化して初期化します。

移行の例

// BEFORE (using PublicClientNext)
import { PublicClientNext } from "@azure/msal-browser";

const pca = PublicClientNext.createPublicClientApplication(config);

// AFTER (standard usage)
import { PublicClientApplication } from "@azure/msal-browser";

const pca = new PublicClientApplication(config);
await pca.initialize();

// AFTER (nested app support)
import { createNestablePublicClientApplication } from "@azure/msal-browser";

const pca = await createNestablePublicClientApplication(config);

// AFTER (standard)
import { createStandardPublicClientApplication } from "@azure/msal-browser";

const pca = await createStandardPublicClientApplication(config);

ほとんどのアプリケーションでは、 PublicClientNext.createPublicClientApplication(config) を new PublicClientApplication(config) に置き換える必要があります。以前に supportsNestedAppAuth 構成オプションを使用していた場合は、代わりに createNestablePublicClientApplication(config) に移行します。

PublicClientApplication.createPublicClientApplication 静的関数の削除

createPublicClientApplicationのPublicClientApplication静的関数は削除され、個別にエクスポートされたcreateStandardPublicClientApplicationに置き換えられました。

移行の例

// BEFORE
import { PublicClientApplication } from "@azure/msal-browser";

const pca = await PublicClientApplication.createPublicClientApplication(config);

// AFTER
import { createStandardPublicClientApplication } from "@azure/msal-browser";

const pca = await createStandardPublicClientApplication(config);

構成の変更

BrowserAuthOptions の変更

skipAuthorityMetadataCache パラメーターが Configuration の BrowserAuthOptions から削除されました。
protocolMode パラメーターは、Configuration の BrowserAuthOptions ではなく SystemOptions に移動されました。
supportsNestedAppAuth パラメーターは削除されました。入れ子になったアプリの createNestablePublicClientApplication API を代わりに使用します。入れ子になったアプリの詳細については、こちらをご覧ください。
navigateTologinRequestUrl パラメーターは Configuration の BrowserAuthOptions から削除されました。代わりに、handleRedirectPromiseの呼び出しのパラメーターとして options オブジェクト内で指定できるようになりました。
```
pca.handleRedirectPromise({ navigateToLoginRequestUrl: false });
```
encodeExtraQueryParams パラメーターは削除されました。追加のクエリパラメーターはすべてエンコードされます。

supportsNestedAppAuth パラメーターは削除されました。 createNestablePublicClientApplication() を代わりに使用します。

    // BEFORE
    const pca = new PublicClientApplication({
        auth: {
            clientId: "your-client-id",
            authority: "https://login.microsoftonline.com/common"
            supportsNestedAppAuth: true
        },
    });

    // AFTER
    const pca = await createNestablePublicClientApplication({
        auth: {
            clientId: "your-client-id",
            authority: "https://login.microsoftonline.com/common"
        }
    });

OIDCOptions パラメーターは、ResponseModeではなくServerResponseTypeを受け取るようになりました。 ResponseMode.QUERYではなく、ServerResponseType.QUERYやResponseMode.FRAGMENTの代わりにServerResponseType.FRAGMENTを使用してください。

CacheOptions の変更

次のパラメーターは MSAL Browser v4 で非推奨となり、v5 の CacheOptions から削除されました。

temporaryCacheLocation
claimsBasedCachingEnabled - アクセストークンは、要求された要求に基づいて格納されなくなりました。
storeAuthStateInCookie
secureCookies - すべての Cookie が HTTPS 経由でのみ安全に送信されるようになりました。
cacheMigrationEnabled

システムオプション

protocolMode パラメーターは、Configuration のSystemOptionsからBrowserAuthOptionsに移動されました。オプションや機能に変更はありません。
navigateFrameWait パラメーターは削除されました。これは以前、MSAL.jsでサポートされなくなった古いブラウザーで必要とされていました。
iframeHashTimeoutパラメーターと windowHashTimeout パラメーターは、それぞれ iframeBridgeTimeout および popupBridgeTimeout に置き換えられました。これらのタイムアウトは、BroadcastChannel API 経由でリダイレクトブリッジからの応答を待機する時間を制御するようになりました。

`asyncPopups`

asyncPopups パラメーターの名前が navigatePopups で SystemOptions に変更され、オプションが逆になります。ポップアップを開いて後で移動するかどうかを設定します。 true に設定すると、空白のポップアップが開き、ログインドメインに移動します。 false に設定すると、ポップアップがログインドメインに直接開かれます。これは、デスクトップアプリやプログレッシブ Web アプリなど、 about:blank がサポートされていないシナリオでは false に設定できます。

Important

既定では、 navigatePopups は true に設定されます。以前 asyncPopups を使用していた場合は、 navigatePopups に変更し、構成を元に戻す必要があります。

詳細については、構成に関するドキュメントを参照してください。

要求時の変更

`onRedirectNavigate` パラメーターの削除

onRedirectNavigate パラメーターは、今後のオブジェクトConfiguration、RedirectRequestおよびEndSessionRequest オブジェクトから削除されます。使用する必要がある場合は、msal 構成で設定してください。

追加の要求パラメーターの統合

次の要求パラメーターが削除されました。

authorizePostBodyParams
tokenBodyParameters
tokenQueryParameters

追加の要求パラメーターを簡略化するには、新しい extraParameters 要求オプションで汎用の追加パラメーターを使用する必要があります。リクエストで extraParameters が設定されている場合、それらは、リクエストで構成されている httpMethod（既定値は GET）に応じて、URL のクエリ文字列またはリクエスト本文内のすべてのトークンサービス呼び出しで送信されます。 URL クエリ文字列に含まれている必要がある追加のパラメーターを送信するには、 extraQueryParameters 引き続き使用できます。

Note

追加のパラメーターを extraQueryStringParameters にするか、 extraParametersに入れるのかわからない場合は、 extraParametersに入る可能性が最も高くなります。

v4（以前の）リクエストの例:

// Example of a GET request with extra parameters
const authRequest = {
    scopes: ["SAMPLE_SCOPE"],
    extraQueryParamters: {
        "dc": "DC_VALUE" // This was sent on the query string on GET /authorize
    },
    tokenBodyParameters: {
        "extra_parameters_assertion": "ASSERTION_VALUE" // This was sent on the POST body to /token
    },
    tokenQueryParamters: {
        "slice": "SLICE_VALUE" // This was sent on the query string on POST /token
    }
}

// Example of a POST request with extra parameters
const authRequest = {
    scopes: ["SAMPLE_SCOPE"],
    httpMethod: "POST", // default is "GET" -> Determines method for "/authorize" call. Calls to "/token" are always POST
    extraQueryParamters: {
        "dc": "DC_VALUE" // This was sent on the query string on POST /authorize
    },
    authorizePostBodyParameters: {
        "extra_parameters_assertion": "ASSERTION_VALUE", // This was sent on the body on POST /authorize
    }
    tokenBodyParameters: {
        "extra_parameters_assertion": "ASSERTION_VALUE" // This was sent on the POST body to /token
    },
    tokenQueryParamters: {
        "slice": "SLICE_VALUE" // This was sent on the query string on POST /token
    }
}

v5 リクエストの例

// Example of a GET request with extra parameters
const authRequest = {
    scopes: ["SAMPLE_SCOPE"],
    extraQueryParamters: {
        // Will be sent in query string to /authorize and /token
        "dc": "DC_VALUE",
        "slice": "SLICE_VALUE"
    },
    extraParameters: {
        "extra_parameters_assertion": "ASSERTION_VALUE", // Will be sent in query string to /authorize and in body to /token
    },
};

// Example of a POST request with extra parameters
const authRequest = {
    scopes: ["SAMPLE_SCOPE"],
    httpMethod: "POST", // default is "GET" -> Determines method for "/authorize" call. Calls to "/token" are always POST
    extraQueryParamters: {
        // Will be sent in query string to /authorize and /token
        "dc": "DC_VALUE",
        "slice": "SLICE_VALUE"
    },
    extraParameters: {
        extra_parameter_assertion: "assertion_value", // Will be sent in post body to /authorize and /token
    },
};

Note

MSAL によって、 extraParameters を URL 文字列にエンコードする必要があると判断された場合、 extraParameters は同じ名前のパラメーターを上書きする方法で extraQueryParams とマージされます。このような場合、 extraParameters のパラメーターの値は、 extraQueryParamsの値よりも優先されます。

Cross-Origin-Opener-Policy (COOP) 対応

MSAL Browser v5 には、クロスオリジンOpener-Policy (COOP) の組み込みサポートが導入されています。これにより、参照コンテキストを分離することでセキュリティが強化されます。認証サービス (Microsoft Entra IDまたは Azure AD B2C) が COOP ヘッダーを返すと、従来のポップアップおよびサイレント iframe 認証フローが制限されます。 MSAL v5 には、COOP 対応環境での認証を処理するためのリダイレクトブリッジメカニズムが用意されています。

Note

Microsoft Entra ID (以前のAzure AD) では、COOP が既定で有効になっています。 Azure AD B2C の場合、COOP の可用性は、バックエンド構成と使用されている認証エンドポイントによって異なります。

変更された内容

認証サービスの応答 ( Cross-Origin-Opener-Policy: same-origin など) に COOP ヘッダーが存在する場合、認証ウィンドウがメインアプリケーションウィンドウと通信できないため、従来のポップアップおよびサイレント iframe 認証フローは失敗します。 MSAL v5 は、リダイレクトブリッジパターンを導入することでこれを解決します。

すべての認証フロー (acquireTokenSilent()、 ssoSilent()、 loginPopup()、 loginRedirect()) でリダイレクトブリッジが使用されるようになりました。リダイレクトブリッジは、フローに基づいて認証応答を異なる方法で処理します。

ポップアップフローとサイレントフロー: リダイレクトブリッジは、BroadcastChannel API を使用してメインアプリケーションウィンドウに認証応答をブロードキャストします
リダイレクトフロー: リダイレクトブリッジは、URL の認証応答を使用してリダイレクトを開始したアプリケーションのページに戻ります

しくみ

メインアプリケーション: アプリケーションは、loginPopup()、ssoSilent()、または loginRedirect() を使用して認証を開始します
リダイレクト: MSAL は、機関ページへのポップアップ/iframe/ウィンドウを開きます
認証フロー: 機関ページが OAuth フローを完了し、認証応答を受け取ります
応答処理: リダイレクトページでは、次の新しい broadcastResponseToMainFrame() 関数が使用されます。
- ポップアップ/サイレントフローの場合: BroadcastChannel API を使用してメインウィンドウに応答をブロードキャストします
- リダイレクトフローの場合: 認証応答でacquireTokenRedirectが開始されたページに移動します
トークンの取得: メインアプリケーションが応答を受け取り、トークンの取得を完了します

移行の手順

1. リダイレクトブリッジページを設定する

broadcastResponseToMainFrame()から@azure/msal-browser/redirect-bridgeを呼び出すページを作成します。このページは COOP ヘッダーと共に提供 しないでください 。

セットアップはビルドシステムによって異なります。 リダイレクトブリッジのセットアップガイド Framework-Specific 参照してください。

フレームワーク	Approach
角度	ルートコンポーネント + 省略可能な `angular.json` アセット
Vite	複数ページ `rollupOptions.input`
Webpack	別個のエントリ + `HtmlWebpackPlugin`
Next.js	`MsalProvider` から除外されるページコンポーネント
CRA (React アプリの作成)	静的 `public/redirect.html` ページ
Express.js	サーバー側 COOP ヘッダーの除外

「リダイレクト URI に関する考慮事項 | | 」も参照してください。

2. MSAL 構成を更新する

redirectUriを新しいリダイレクトブリッジページにポイントします。

const msalConfig = {
    auth: {
        clientId: "{your-client-id}",
        authority: "https://login.microsoftonline.com/common",
        redirectUri: "https://{your-app-home-page}/redirect",
    },
};

Important

また、Entra ID アプリの登録でリダイレクト URI を更新する必要があります。 URI は、パス、プロトコル、ポートなど、 正確に 一致する必要があります。これを行わないと、 redirect_uri_mismatch エラーが発生します。

動作の破壊的変更

イベントの種類と InteractionStatus の変更

イベントの種類と InteractionStatus を統合し、発生した API ではなく、何が起こったかを反映しました。

SSO_SILENT および ACQUIRE_TOKEN_BY_CODE イベントは、 ACQUIRE_TOKEN イベント (START/SUCCESS/FAILURE バリアント) に置き換えられました
ACCOUNT_ADDED ACCOUNT_REMOVEDは、それぞれLOGIN_SUCCESSとLOGOUT_SUCCESSに置き換えられました。
LOGIN_START LOGIN_FAILUREは、それぞれACQUIRE_TOKEN_STARTとACQUIRE_TOKEN_FAILUREに置き換えられました。
LOGIN_SUCCESSのペイロードがAccountInfo オブジェクトになりました。
ログインが成功すると、 LOGIN_SUCCESS イベントと ACQUIRE_TOKEN_SUCCESS イベントの両方が出力されるようになりました。

`LOGIN_SUCCESS` ペイロードの種類の移行

イベントコールバックで現在 LOGIN_SUCCESS ペイロードを AuthenticationResult にキャストしている場合は、LOGIN_SUCCESS には AccountInfo を使用するように更新し、ACQUIRE_TOKEN_SUCCESS には AuthenticationResult を使用してください。

// BEFORE (v4-style assumption)
import {
    EventType,
    AuthenticationResult,
} from "@azure/msal-browser";

pca.addEventCallback((event) => {
    if (event.eventType === EventType.LOGIN_SUCCESS) {
        const result = event.payload as AuthenticationResult;
        setAccount(result.account); // Will silently fail in v5 where payload is AccountInfo, not AuthenticationResult
    }
});

// AFTER (v5-safe handling)
import {
    EventType,
    AuthenticationResult,
    AccountInfo,
} from "@azure/msal-browser";

pca.addEventCallback((event) => {
    if (event.eventType === EventType.LOGIN_SUCCESS) {
        const account = event.payload as AccountInfo;
        setAccount(account);
    }

    if (event.eventType === EventType.ACQUIRE_TOKEN_SUCCESS) {
        const result = event.payload as AuthenticationResult;
        setAccessToken(result.accessToken);
    }
});

エラーメッセージ形式の変更

バンドルサイズを小さくするために、エラーメッセージがバンドルから移動されました。エラーがスローされると、 message プロパティは、説明的なエラーメッセージではなく、エラードキュメントへの汎用リンクを返すようになりました。

// BEFORE (v4)
error.message = "Token request cannot be made without authorization code or refresh token.";

// AFTER (v5)
error.message = "See https://aka.ms/msal.js.errors#request_cannot_be_made for details";

errorCode プロパティは変更されず、特定のエラーを識別するために引き続き使用できます。エラーの詳細な説明については、エラーのドキュメントを参照してください。

Important

アプリケーションが error.message プロパティの解析または表示に依存している場合は、代わりに errorCode を使用するようにエラー処理コードを更新するか、ユーザーをドキュメントリンクに誘導する必要があります。

エラー処理コードの更新

ユーザーにエラーを表示する場合は、errorCodeを直接表示するのではなく、error.messageをわかりやすいメッセージにマップします。

// BEFORE (v4)
showError(error.message);

// AFTER (v5) — use errorCode for user-facing messages
const userMessages = {
    request_cannot_be_made: "Please sign in again to continue.",
    interaction_required: "Additional verification is needed.",
    consent_required: "Administrator approval is required for this action.",
    login_required: "Your session has expired. Please sign in again.",
    // Add mappings for error codes your application encounters
};
showError(userMessages[error.errorCode] || "An authentication error occurred.");

条件付きロジックのエラーを解析する場合は、 message の文字列一致から errorCode の比較に切り替えます (これは v4 で既に推奨されているアプローチでした)。

// BEFORE (v4) — fragile, relied on message text
if (error.message.includes("interaction_required")) {
    await msalInstance.acquireTokenPopup(request);
}

// AFTER (v5) — use errorCode (stable across versions)
if (error.errorCode === "interaction_required") {
    await msalInstance.acquireTokenPopup(request);
}

診断のエラーをログに記録する場合は、 errorCode と message の両方を含めます (メッセージには関連するドキュメントへの直接リンクが含まれるようになりました)。

// AFTER (v5) — log errorCode for programmatic use, message for the docs link
logger.error(`MSAL Error [${error.errorCode}]: ${error.message}`);
// Output: MSAL Error [request_cannot_be_made]: See https://aka.ms/msal.js.errors#request_cannot_be_made for details

Tip

errorCodeの値は v4 と v5 の間で同じです。message形式のみが変更されています。既存のコードが既に errorCodeで分岐している場合、変更は必要ありません。

コンソールログの変更

バンドルサイズを小さくするために、コンソールログメッセージがハッシュされるようになりました。ブラウザーコンソールに完全なログメッセージが表示されるのではなく、ハッシュ値が表示されます。

// BEFORE (v4)
[Wed, 15 Jan 2025 10:30:45 GMT] : abc-123 : @azure/msal-browser@4.27.0 : Info - Returning token from cache

// AFTER (v5)
[Wed, 15 Jan 2025 10:30:45 GMT] : abc-123 : @azure/msal-browser@5.0.0 : Info - 7f3a9b2c

ブラウザーコンソールでのデバッグには、ログをデコードするための追加の手順が必要です。ハッシュされたログを読み取り可能なメッセージにデコードするには、デコードスクリプトを使用します。デコードスクリプトの使用方法の詳細については、スクリプトのドキュメントを参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-02

MSAL Browser v4 から v5 への移行

API の破壊的変更

SignedHttpRequest.removeKeys 戻り値の型が変更されました

TokenCache と loadExternalTokens

handleRedirectPromise API シグネチャが変更されました

PublicClientApplication の一部の機能の削除

startPerformanceMeasurement() の削除

PublicClientNext の削除

移行の例

PublicClientApplication.createPublicClientApplication 静的関数の削除

移行の例

構成の変更

BrowserAuthOptions の変更

CacheOptions の変更

システム オプション

asyncPopups

要求時の変更

onRedirectNavigate パラメーターの削除

追加の要求パラメーターの統合

v4（以前の）リクエストの例:

v5 リクエストの例

Cross-Origin-Opener-Policy (COOP) 対応

変更された内容

しくみ

移行の手順

1. リダイレクト ブリッジ ページを設定する

2. MSAL 構成を更新する

動作の破壊的変更

イベントの種類と InteractionStatus の変更

LOGIN_SUCCESS ペイロードの種類の移行

エラー メッセージ形式の変更

エラー処理コードの更新

コンソールログの変更

フィードバック

その他のリソース

`handleRedirectPromise` API シグネチャが変更されました

`PublicClientApplication` の一部の機能の削除

`startPerformanceMeasurement()` の削除

`PublicClientNext` の削除

システムオプション

`asyncPopups`

`onRedirectNavigate` パラメーターの削除

1. リダイレクトブリッジページを設定する

`LOGIN_SUCCESS` ペイロードの種類の移行

エラーメッセージ形式の変更