Azure Identity plugin for brokered authentication

このパッケージはJavaScript用のAzure Identityライブラリ(@azure/identity)へのプラグインを提供し、WAMのような認証ブローカーの使用を可能にします。

認証ブローカーは、接続されているアカウントの認証ハンドシェイクとトークンメンテナンスを管理するユーザーのマシン上で実行されるアプリケーションです。現在、Windows 認証ブローカーであるWeb Account Manager(WAM)のみがサポートされています。

ソースコード | Samples | API reference documentation | Microsoft Entra ID documentation

はじめ

import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

前提条件

Azureのサブスクリプション。

注: @azure/identity-broker を使用したローカル開発の場合は、追加のツールをインストールする必要がある場合があります。 node-gyp は、システム API にアクセスするためのアドオンをコンパイルするために使用されます。インストール要件は、 node-gyp README に記載されています。

Linux では、ライブラリは libsecret を使用するため、インストールが必要になる場合があります。ディストリビューションに応じて、次のコマンドを実行する必要があります。

デビアン/Ubuntu: sudo apt-get install libsecret-1-dev
Red Hatベース: sudo yum install libsecret-devel
アーチLinux: sudo pacman -S libsecret

注

ブローカー認証は現在、WindowsとLinuxでのみサポートされています。 macOS はまだサポートされていません。

パッケージをインストールする

このパッケージはJavaScript用のAzure Identityで使用することを想定して設計されています。 @azure/identityを使用して、npm とこのパッケージの両方をインストールします。

npm install --save @azure/identity
npm install --save @azure/identity-broker

サポートされている環境

JavaScript用のAzure Identityプラグインは、v20から安定版(偶数番号付き)の Node.js をサポートしています。プラグインは他の Node.js バージョンで実行される可能性があります。サポートは保証されません。 @azure/identity-broker は、ブラウザー環境をサポート。

主な概念

もし@azure/identityやMicrosoft Entra IDを使うのが初めてなら、まずUsing @azure/identity with Microsoft Entra IDを読むことをお勧めします。このドキュメントはプラットフォームの理解とAzureアカウントの正しい設定方法を詳しく理解してくれます。

親ウィンドウハンドル

InteractiveBrowserCredentialを介してブローカーを使用して認証する場合、要求ウィンドウで認証ダイアログが正しく表示されるようにするには、親ウィンドウハンドルが必要です。デバイス上のグラフィカルユーザーインターフェイスのコンテキストでは、ウィンドウハンドルはオペレーティングシステムが各ウィンドウに割り当てる一意の識別子です。 Windowsオペレーティングシステムの場合、このハンドルは特定のウィンドウを参照するための整数値です。

Microsoft アカウント (MSA) パススルー

Microsoftアカウント(MSA)は、ユーザーがMicrosoft サービスにアクセスするために作成した個人アカウントです。 MSA パススルーは従来の構成であり、ユーザーは通常 MSA ログインを受け入れないリソースにトークンを取得できます。この機能は、ファーストパーティのアプリケーションでのみ使用できます。 MSA パススルーを使用するように構成されたアプリケーションで認証するユーザーは、legacyEnableMsaPassthrough を true 内の InteractiveBrowserCredentialNodeOptions.brokerOptions に設定して、これらの個人アカウントを WAM で一覧表示できるようにします。

リダイレクト URI

Microsoft Entraアプリケーションは、ユーザーがログイン後に認証応答をどこに送るかを決定するためにリダイレクトURIに依存しています。 WAM を介してブローカー認証を有効にするには、次のパターンに一致するリダイレクト URI をアプリケーションに登録する必要があります。

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Azure Identity plugins

バージョン 2.0.0 @azure/identity 時点で、JavaScript 用の ID クライアントライブラリにはプラグイン API が含まれています。このパッケージ (@azure/identity-broker) は、useIdentityPlugin パッケージから最上位 @azure/identity 関数に引数として渡す必要があるプラグインオブジェクトをエクスポートします。次のように、プログラムでネイティブブローカーを有効にします。

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

useIdentityPluginを呼び出すと、ネイティブブローカープラグインが @azure/identity パッケージに登録され、WAM ブローカー認証をサポートする InteractiveBrowserCredential で使用できるようになります。この資格情報は、コンストラクターオプションに brokerOptions。

Notes: @azure/identityバージョン4.11.0-beta.1以降、DefaultAzureCredentialはWindowsウェブアカウントマネージャーからのサインインをサポートしています。次のように、プログラムでネイティブブローカーを有効にします。

import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

例

プラグインが登録されたら、brokerOptions プロパティが資格情報コンストラクターに enabled に設定された true を渡すことで、WAM ブローカー認証を有効にすることができます。次の例では、InteractiveBrowserCredentialを使用します。

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";

// Print out part of the access token
console.log((await credential.getToken(scope)).token.substring(0, 10), "...");

Electronアプリを使ってウィンドウハンドルを取得する完全な例については、このサンプルを参照してください。

useDefaultBrokerAccount オプションが trueに設定されている場合、資格情報は既定のブローカーアカウントをサイレントモードで使用しようとします。既定のアカウントを使用できない場合、資格情報は対話型認証にフォールバックします。

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    useDefaultBrokerAccount: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";

// Print out part of the access token
console.log((await credential.getToken(scope)).token.substr(0, 10), "...");

トラブルシューティング

さまざまな故障シナリオの診断方法については、Azure Identity troubleshooting guideをご覧ください。

伐採

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。または、setLogLevelで @azure/logger を呼び出すことによって、実行時にログを有効にすることもできます。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

次の手順

フィードバックを提供する

バグに遭遇したり提案があれば、open a issueをお願いします。

貢献

このライブラリに貢献したい場合は、contributing guideをご覧ください。コードのビルドやテスト方法について詳しく学べます。

フィードバック

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

Last updated on 2026-04-10