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

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

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

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

作業の開始

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

useIdentityPlugin(nativeBrokerPlugin);

前提条件

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

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

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

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

サポートされている環境

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

主要な概念

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

親ウィンドウ ハンドル

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

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

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

リダイレクト URI

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

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

Azure Identity プラグイン

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

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

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
  },
});

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

例

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

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

useIdentityPlugin(nativeBrokerPlugin);

async function main() {
  const credential = new InteractiveBrowserCredential({
    brokerOptions: {
      enabled: true,
      parentWindowHandle: <insert_current_window_handle>
    },
  });

  // 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), "...");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

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

サインインに既定のアカウントを使用する

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

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

useIdentityPlugin(nativeBrokerPlugin);

async function main() {
  const credential = new InteractiveBrowserCredential({
    brokerOptions: {
      enabled: true,
      useDefaultBrokerAccount: true,
      parentWindowHandle: <insert_current_window_handle>
    },
  });

  // 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), "...");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

トラブルシューティング

さまざまな障害シナリオを診断する方法の詳細については、Azure ID [トラブルシューティング ガイド][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.0.1/sdk/identity/identity/TROUBLESHOOTING.md] を参照してください。

ログの記録

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

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

setLogLevel("info");

次のステップ

フィードバックの提供

バグが発生した場合や提案がある場合は、issue をオープンしてください。

共同作成

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