次の方法で共有

ブローカー認証用の Azure ID プラグイン

  • [アーティクル]

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

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

ソース コード | サンプル | API リファレンス ドキュメント |[Microsoft Entra ID のドキュメント](https://learn.microsoft.com/entra/identity/)

はじめ

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

useIdentityPlugin(nativeBrokerPlugin);

前提 条件

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

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

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

サポートされている環境

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

主な概念

@azure/identity または Microsoft Entra ID を初めて使用する場合は、最初に Microsoft Entra ID で @azure/identity を使用する を読 することをお勧めします。 このドキュメントでは、プラットフォームと Azure アカウントを正しく構成する方法について理解を深めます。

親ウィンドウ ハンドル

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

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

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

リダイレクト URI

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

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

Azure ID プラグイン

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

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。

例

プラグインが登録されたら、enabled プロパティが資格情報コンストラクターに true に設定された brokerOptions を渡すことで、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 ID の [トラブルシューティング ガイド][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.1.0/sdk/identity/identity/TROUBLESHOOTING.md] を参照してください。

伐採

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

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

setLogLevel("info");

次の手順

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

バグが発生した場合や提案がある場合は、問題開いてください。

貢献

このライブラリに投稿する場合は、の投稿ガイド を参照して、コードをビルドしてテストする方法の詳細を確認してください。

インプレッション