ネイティブ トークン ブローカーでの MSAL ノードの使用 (Windows)

Microsoft Authentication Library (MSAL) ノードでは、ネイティブ トークン ブローカーからのトークンの取得がサポートされています。 ネイティブ ブローカーを使用する場合、更新トークンは取得されたデバイスにバインドされ、 msal-node やアプリケーションからはアクセスできません。 これにより、 msal-node だけでは実現できない、より高いレベルのセキュリティが提供されます。

この記事では、Windows ブローカーを構成し、所有証明を設定し、ブローカー固有の動作を理解する方法について説明します。

ブローカーのサポートは、次のプラットフォームで利用できます。

ブローカーとは

認証ブローカーは、ユーザーのコンピューター上で実行され、接続されているアカウントの認証ハンドシェイクとトークンのライフサイクルを管理するコンポーネントです。 Windowsでは、このロールは Web アカウント マネージャー (WAM) によって実行されます。 主な利点は次のとおりです。

• セキュリティの強化。 セキュリティの強化は、アプリ コードの変更を必要とせずに、OS またはブローカーの更新プログラムを介して提供されます。 更新トークンはデバイスにバインドされ、流出から保護されます。
• 機能のサポート。 追加のスキャフォールディング コードなしで、Windows Hello、Microsoft Entra 条件付きアクセス ポリシー、Fast Identity Online (FIDO) セキュリティ キーなどの豊富な OS 機能にアクセスできます。
• システム統合。 アプリケーションは組み込みのアカウント ピッカーに接続されるため、ユーザーは資格情報を再入力する代わりに既存のアカウントをすばやく選択できます。
• トークン保護。 ブローカーは、更新トークンがデバイスにバインドされていることを確認し、 アプリが所有証明アクセス トークンを取得できるようにします。

サポートされているアーキテクチャ

• Windows: x64、x86、ARM64

Prerequisites

• Node.js 18 以降
• 依存関係として @azure/msal-node-extensions をインストールする
• ブローカーのリダイレクト URI をアプリの登録に登録します。 必要な値については、「 リダイレクト URI」を参照してください。

リダイレクト URI

Azure ポータルのモバイル およびデスクトップ アプリケーション プラットフォームに、次のリダイレクト URI を登録します。

ms-appx-web://Microsoft.AAD.BrokerPlugin/<your-client-id>

<your-client-id>をアプリケーションのクライアント ID に置き換えます。

機能の有効化

トークン ブローカーを有効にするには、構成パラメーターを 1 つだけ必要とします。 ブローカー構成で NativeBrokerPlugin インスタンスを渡します。

import { PublicClientApplication, Configuration } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id",
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin(),
    },
};

const pca = new PublicClientApplication(msalConfig);

実際のサンプルは、 auth-code-cli-brokered-app サンプルにあります。

ウィンドウのペアレンティング

認証プロンプトが呼び出し元のアプリケーションに表示され、それ以上の対話をブロックするには、アプリケーションのウィンドウ ハンドルを acquireTokenInteractive API に提供します。

CLI アプリでは、ウィンドウ ハンドルを検索するためのベスト エフォート試行が内部で行われますが、信頼性が低い場合があります。

Electron を使用している場合は、 getNativeWindowHandle API を使用し、結果を acquireTokenInteractiveに渡します。

import { BrowserWindow } from "electron";

const win = new BrowserWindow();
const pca = new PublicClientApplication(msalConfig);

pca.acquireTokenInteractive({
    windowHandle: win.getNativeWindowHandle(),
});

所持証明

アクセス トークン所有証明 (PoP) は、ネイティブ ブローカーを介してトークンを取得するときにサポートされます。 PoP トークンを要求するには、 acquireTokenInteractive または acquireTokenSilentに指定された要求オブジェクトに次のプロパティを追加します。

AT PoP リクエスト パラメータ

使用例

この例では、認証スキームと署名付き HTTP 要求プロパティを設定して、所有証明トークンを要求します。

import { PublicClientApplication, Configuration, AuthenticationScheme } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id",
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin(),
    },
};

const pca = new PublicClientApplication(msalConfig);

const popTokenRequest = {
    scopes: ["User.Read"],
    authenticationScheme: AuthenticationScheme.POP,
    resourceRequestMethod: "POST",
    resourceRequestUri: "YOUR_RESOURCE_ENDPOINT",
    shrNonce: "NONCE_ACQUIRED_FROM_RESOURCE_SERVER",
};

pca.acquireTokenInteractive(popTokenRequest);
pca.acquireTokenSilent(popTokenRequest);

Windows ブローカーを使用する場合の違い

ネイティブ ブローカーを使用してトークンを取得するときに、動作が異なる場合がいくつかあります。

• forceRefresh呼び出しのacquireTokenSilent パラメーターはサポートされていません。 このフラグの設定に関係なく、ブローカーからキャッシュされたトークンを受け取ることがあります。
• ブローカーがユーザーに対話を求める必要がある場合は、システム プロンプトが開きます。 これにより、ブラウザー ウィンドウで認証が行われないため、ユーザー エクスペリエンス (UX) が変更されます。
• アクセス トークンの所有証明 は ブローカーによってサポートされますが、ブローカー以外のフローではサポート されていません 。