JavaScript 用 Azure ID クライアント ライブラリ - バージョン 4.5.0

Azure Identity ライブラリでは、便利な一連の TokenCredential 実装を通じて、Microsoft Entra ID (以前の Azure Active Directory)) トークン認証を できます。

さまざまな資格情報の例については、Azure ID の例に関するページを参照してください。

主要なリンク:

• ソース コード の
• パッケージ (npm)
• API リファレンス ドキュメント
• Microsoft Entra 身分証明書類
• サンプル

はじめ

現在サポートされている環境

• Node.js の LTS バージョンを する
• Safari、Chrome、Edge、Firefox の最新バージョン。
  • 注: このライブラリでエクスポートされるさまざまな資格情報のうち、ブラウザーでサポートされている資格情報は InteractiveBrowserCredential だけです。

詳細については、サポート ポリシーのを参照してください。

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

npmを使用して Azure Identity をインストールします。

npm install --save @azure/identity

前提 条件

• Azure サブスクリプション。
• 省略可能: Azure CLI や Azure PowerShell は、開発環境での認証やアカウント ロールの管理にも役立ちます。

どのようなときに @azure/identity を使用するか

@azure/identity によって公開される資格情報クラスは、Azure SDK クライアントをローカル、開発環境、運用環境で認証するための最も簡単な方法を提供することに重点を置いています。 Azure で可能なほとんどの認証シナリオをカバーするために、認証プロトコルのシンプルさと合理的なサポートを目指しています。 さらに多くのシナリオに対応できるように、積極的に拡張しています。 提供される資格情報の完全な一覧については、「資格情報クラスの」セクションを参照してください。

@azure/identity によって提供されるすべての資格情報の種類は、Node.jsでサポートされています。 ブラウザーの場合、InteractiveBrowserCredential は基本認証シナリオで使用される資格情報の種類です。

@azure/identity によって提供される資格情報の種類のほとんどは、Microsoft Authentication Library for JavaScript (MSAL.js)を使用します。 具体的には、V2 MSAL.js ライブラリを使用します。このライブラリは、PKCE OAuth 2.0 認証コード フローを使用し、OpenID 準拠のします。 @azure/identity はシンプルさに重点を置いていますが、@azure/msal-common、@azure/msal-node、@azure/msal-browserなどの MSAL.js ライブラリは、Azure がサポートする認証プロトコルの堅牢なサポートを提供するように設計されています。

他のものを使用する場合

@azure/identity 資格情報の種類は、@azure/core-auth's TokenCredential クラスの実装です。 原則として、getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> を満たす getToken メソッドを持つオブジェクトは、TokenCredentialとして機能します。 つまり、開発者は、@azure/identityでカバーされていない認証ケースをサポートするために、独自の資格情報の種類を記述できます。 詳細については、「カスタム資格情報を する」を参照してください。

資格情報の種類は多くの高度なシナリオをサポートしていますが、開発者は代わりに、Microsoft Authentication Library for JavaScript (MSAL.js) を直接使用できます。 次のシナリオでは、MSAL.js の使用を検討してください。

• 認証プロトコルとその構成を完全に制御する必要のある開発者。
• 資格情報の種類は、コア HTTP レイヤーで処理されるインテリジェントなキャッシュとトークンの更新を使用する Azure SDK クライアントで使用するように設計されています。 getToken を直接使用する必要がある場合は、認証フローとトークン キャッシュをより詳細に制御するために MSAL.js を使用するとメリットがあります。

詳細については、次のリンクを参照してください。

• @azure/identity のいくつかの高度なユース ケースは、Azure ID の例 ページで説明します。
  • ここでは、特に 高度な例の セクションがあります。
  • また、MSAL で直接認証 方法を示すセクションもあります。

ブラウザーの高度な認証ワークフローについては、@azure/msal-browser ライブラリを直接使用して Azure SDK クライアントを認証する方法を紹介するセクションがあります。

開発環境でクライアントを認証する

Azure でホストされるアプリケーションではマネージド ID を使用することをお勧めしますが、開発者は、コードをローカルでデバッグして実行するときに、独自のアカウントを使用して Azure サービスの呼び出しを認証するのが一般的です。 開発環境でこの認証を実行するために使用できる開発者ツールがいくつかあります。

Azure Developer CLI を使用して認証する

IDE の外部でコーディングする開発者は、Azure Developer CLI を使用して認証することもできます。 その後、DefaultAzureCredential または AzureDeveloperCliCredential を使用するアプリケーションは、ローカルで実行するときに、このアカウントを使用してアプリケーションの呼び出しを認証できます。

Azure Developer CLIを使用して認証するには、コマンド azd auth loginを実行します。 既定の Web ブラウザーを使用してシステムで実行されているユーザーの場合、Azure Developer CLI によってブラウザーが起動され、ユーザーが認証されます。

既定の Web ブラウザーがないシステムの場合、azd auth login --use-device-code コマンドはデバイス コード認証フローを使用します。

Azure CLI を使用した認証

AzureCliCredentialを使用するアプリケーションは、直接または DefaultAzureCredentialを使用して、Azure CLI アカウントを使用して、ローカルで実行するときにアプリケーションの呼び出しを認証できます。

Azure CLIで認証するには、コマンド az loginを実行します。 既定の Web ブラウザーを使用してシステム上で実行されているユーザーの場合、Azure CLI によってブラウザーが起動され、ユーザーが認証されます。

Azure CLI アカウントサインイン の

既定の Web ブラウザーがないシステムの場合、az login コマンドはデバイス コード認証フローを使用します。 ユーザーは、--use-device-code 引数を指定してブラウザーを起動するのではなく、デバイス コード フローを使用するように Azure CLI に強制することもできます。

Azure CLI アカウントのデバイス コード サインイン の

Azure PowerShell を使用して認証する

AzurePowerShellCredentialを使用するアプリケーションは、直接または DefaultAzureCredentialを使用して、Azure PowerShell に接続されているアカウントを使用して、ローカルで実行するときにアプリケーションの呼び出しを認証できます。

Azure PowerShell認証するには、 コマンドレットを実行します。 既定では、Azure CLI と同様に、Connect-AzAccount は既定の Web ブラウザーを起動してユーザー アカウントを認証します。

Azure PowerShell アカウントのサインイン の

セッションで対話型認証をサポートできない場合、-UseDeviceAuthentication 引数は、Azure CLI 資格情報の対応するオプションと同様に、代わりにデバイス コード認証フローを使用するようにコマンドレットに強制します。

Visual Studio Code を使用して認証する

Visual Studio Code を使用する開発者は、Azure アカウント拡張機能 を使用して、エディター経由で認証できます。 VisualStudioCodeCredential を使用するアプリでは、ローカルで実行するときに、このアカウントを使用してアプリの呼び出しを認証できます。

Visual Studio Code で認証するには、Azure アカウント拡張機能がインストールされていることを確認します。 インストールしたら、コマンド パレット を開き、Azure: Sign In コマンドを実行します。

さらに、@azure/identity-vscode プラグイン パッケージを使用します。 このパッケージは、VisualStudioCodeCredential の依存関係を提供し、有効にします。 プラグインのを参照してください。

これは、Azure アカウント拡張機能 0.9.11より新しいバージョンでは機能しない 既知の問題です。 この問題に対する長期的な修正が進行中です。 それまでの間は、Azure CLIを使用した認証 検討してください。

ブラウザーでクライアントを認証する

Web ブラウザー内で Azure SDK クライアントを認証するために、リダイレクトまたはポップアップを使用して認証フローを完了するように設定できる InteractiveBrowserCredentialが用意されています。 最初に、Web アプリケーション用の Azure portal で Azure アプリ登録 を 作成する必要があります。

主な概念

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

資格 情報

資格情報はクラスの一種であり、サービス クライアントが要求を認証するために必要なデータを格納、または取得できます。 Azure SDK 全体のサービス クライアントは、作成時に資格情報を受け入れます。 サービス クライアントは、これらの資格情報を使用してサービスへの要求を認証します。

Azure Id ライブラリは、Microsoft Entra ID による OAuth 認証に重点を置き、サービス要求を認証するために Microsoft Entra トークンを取得できるさまざまな資格情報クラスを提供します。 このライブラリ内のすべての資格情報クラスは、TokenCredential 抽象クラスの実装であり、それらのいずれかを使用して、TokenCredentialで認証できるサービス クライアントを構築できます。

「資格情報クラス を参照してください。

DefaultAzureCredential

DefaultAzureCredential は、Azure ホスティング環境で使用される資格情報とローカル開発で使用される資格情報を組み合わせることで、Azure にデプロイするアプリを開発する際に認証を簡略化します。 詳細については、「DefaultAzureCredential の概要」を参照してください。

継続ポリシー

バージョン 3.3.0 以降、DefaultAzureCredential は、以前に発生した開発者資格情報のエラーに関係なく、成功するまで、すべての開発者資格情報で認証を試みます。 たとえば、開発者の資格情報がトークンの取得を試み、失敗する可能性があるため、DefaultAzureCredential はフロー内の次の資格情報に進みます。 デプロイされたサービス資格情報は、トークンの取得を試みることができるが受信できない場合、スローされた例外でフローを停止します。

これにより、デプロイされた予測可能な動作を持ちながら、コンピューター上のすべての開発者資格情報を試すことができます。

VisualStudioCodeCredential に関する注意

既知の問題により、DefaultAzureCredential トークン チェーンから VisualStudioCodeCredential が削除されました。 今後のリリースで問題が解決されると、この変更は元に戻されます。

プラグイン

Azure Identity for JavaScript には、個別の プラグイン パッケージを通じて特定の機能を提供できるプラグイン API が用意されています。 @azure/identity パッケージは、プラグインを有効にするために使用できる最上位レベルの関数 (useIdentityPlugin) をエクスポートします。 次の 2 つのプラグイン パッケージを提供します。

• @azure/identity-broker。Web アカウント マネージャーなどのネイティブ ブローカーを介したブローカー認証のサポートを提供します。
• @azure/identity-cache-persistence。オペレーティング システムによって提供されるネイティブのセキュリティで保護されたストレージ システムを使用して、Node.js で永続的なトークン キャッシュを提供します。 このプラグインを使用すると、キャッシュされた access_token 値をセッション間で保持できます。つまり、キャッシュされたトークンが使用可能である限り、対話型ログイン フローを繰り返す必要はありません。

例

さまざまな資格情報の使用例については、Azure ID の例ページ

DefaultAzureCredential で認証する

この例では、DefaultAzureCredentialを使用して、@azure/keyvault-keys クライアント ライブラリから KeyClient を認証する方法を示します。

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure vault URL
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();
// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

DefaultAzureCredential を使用してユーザー割り当てマネージド ID を指定する

比較的一般的なシナリオでは、Azure リソースのユーザー割り当てマネージド ID を使用した認証が含まれます。 DefaultAzureCredential を使用したユーザー割り当てマネージド ID の認証に関する 例を調べて、環境変数またはコードを使用して構成できる比較的簡単なタスクにする方法を確認します。

ChainedTokenCredential を使用してカスタム認証フローを定義する

一般に、DefaultAzureCredential は Azure 用アプリケーションの開発を開始する最も簡単な方法ですが、より高度なユーザーは、認証時に考慮される資格情報をカスタマイズする必要があります。 ChainedTokenCredential を使用すると、ユーザーは複数の資格情報インスタンスを組み合わせて、カスタマイズされた資格情報チェーンを定義できます。 この例では、ClientSecretCredentialの異なる 2 つの異なる構成のインスタンスを使用して認証を試みる ChainedTokenCredential を作成し、@azure/keyvault-keysから KeyClient を認証する方法を示します。

import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure variables
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
const tenantId = "<tenant-id>";
const clientId = "<client-id>";
const clientSecret = "<client-secret>";
const anotherClientId = "<another-client-id>";
const anotherSecret = "<another-client-secret>";
// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);
// The chain can be used anywhere a credential is required
const client = new KeyClient(vaultUrl, credentialChain);

マネージド ID のサポート

マネージド ID 認証 は、次の Azure サービスの DefaultAzureCredential または ManagedIdentityCredential 資格情報クラスを介して直接サポートされます。

• Azure App Service と Azure Functions を する
• Azure Arc の
• Azure Cloud Shell
• Azure Kubernetes Service の
• Azure Service Fabric
• Azure Virtual Machines
• Azure Virtual Machines Scale Sets

認証にマネージド ID を使用する方法の例については、例 参照してください。

クラウド構成

資格情報は、既定で Azure パブリック クラウドの Microsoft Entra エンドポイントに対する認証を行います。 Azure Government やプライベート クラウドなどの他のクラウド内のリソースにアクセスするには、コンストラクターの authorityHost 引数を使用して資格情報を構成します。 AzureAuthorityHosts 列挙型は、既知のクラウドの権限を定義します。 US Government クラウドでは、次の方法で資格情報をインスタンス化できます。

import { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  },
);

authorityHost 引数を指定する代わりに、AZURE_AUTHORITY_HOST 環境変数をクラウドの機関の URL に設定することもできます。 この方法は、同じクラウドに対して認証するように複数の資格情報を構成する場合、またはデプロイされた環境でターゲット クラウドを定義する必要がある場合に便利です。

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

AzureAuthorityHosts 列挙型は、便宜上よく知られているクラウドの権限を定義します。ただし、クラウドの権限が AzureAuthorityHostsに一覧表示されていない場合は、任意の有効な機関 URL を文字列引数として渡すことができます。 たとえば次のような点です。

import { ClientSecretCredential } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: "https://login.partner.microsoftonline.cn",
  },
);

すべての資格情報でこの構成が必要なわけではありません。 AzureCliCredentialなどの開発ツールを使用して認証する資格情報は、そのツールの構成を使用します。 同様に、VisualStudioCodeCredential は authorityHost 引数を受け入れますが、既定では Visual Studio Code の Azure: Cloud 設定に一致する authorityHost になります。

資格情報クラス

資格情報チェーン

資格 情報	使い	例
DefaultAzureCredential	Azure で実行されるアプリケーションの開発を迅速に開始するための簡素化された認証エクスペリエンスを提供します。	例
ChainedTokenCredential	ユーザーが複数の資格情報を作成するカスタム認証フローを定義できるようにします。	例

Azure でホストされるアプリケーションを認証する

資格 情報	使い	例
EnvironmentCredential	環境変数で指定された資格情報を使用して、サービス プリンシパルまたはユーザーを認証します。	例
ManagedIdentityCredential	Azure リソースのマネージド ID を認証します。	例
WorkloadIdentityCredential	Kubernetes Microsoft Entra Workload ID をサポートします。	例

サービス プリンシパルを認証する

資格 情報	使い	例	参考
AzurePipelinesCredential	Azure Pipelines Microsoft Entra Workload ID をサポートします。	例
ClientAssertionCredential	署名されたクライアント アサーションを使用してサービス プリンシパルを認証します。	例	サービス プリンシパル認証
ClientCertificateCredential	証明書を使用してサービス プリンシパルを認証します。	例	サービス プリンシパル認証
ClientSecretCredential	シークレットを使用してサービス プリンシパルを認証します。	例	サービス プリンシパル認証

ユーザーの認証

資格 情報	使い	例	参考
AuthorizationCodeCredential	以前に取得した承認コードを使用してユーザーを認証します。	例	OAuth2 認証コード を する
DeviceCodeCredential	UI が制限されたデバイスでユーザーを対話形式で認証します。	例	デバイス コード認証
InteractiveBrowserCredential	既定のシステム ブラウザーを使用してユーザーを対話形式で認証します。 この現象の詳細については、こちらを参照してください。	例	OAuth2 認証コード を する
OnBehalfOfCredential	委任されたユーザー ID とアクセス許可を要求チェーンを介して伝達します。		On-behalf-of authentication
UsernamePasswordCredential	ユーザー名とパスワードを使用してユーザーを認証します。	例	ユーザー名とパスワード認証の

開発ツールを使用した認証

資格 情報	使い	例	参考
AzureCliCredential	Azure CLI を使用して開発環境で認証します。	例	Azure CLI 認証 を する
AzureDeveloperCliCredential	Azure Developer CLI で有効なユーザーまたはサービス プリンシパルを使用して開発環境で認証します。		Azure Developer CLI リファレンス
AzurePowerShellCredential	Azure PowerShell を使用して開発環境で認証します。	例	Azure PowerShell 認証 を する
VisualStudioCodeCredential	Visual Studio Code Azure アカウント拡張機能にサインインしたユーザーとして認証します。		VS Code Azure アカウント拡張機能 を する

環境変数

DefaultAzureCredential と EnvironmentCredential は環境変数で構成できます。 認証の種類ごとに、特定の変数の値が必要です。

シークレットを含むサービス プリンシパル

変数名	価値
AZURE_CLIENT_ID	Microsoft Entra アプリケーションの ID
AZURE_TENANT_ID	アプリケーションの Microsoft Entra テナントの ID
AZURE_CLIENT_SECRET	アプリケーションのクライアント シークレットの 1 つ

証明書を含むサービス プリンシパル

変数名	価値
AZURE_CLIENT_ID	Microsoft Entra アプリケーションの ID
AZURE_TENANT_ID	アプリケーションの Microsoft Entra テナントの ID
AZURE_CLIENT_CERTIFICATE_PATH	秘密キーを含む PEM でエンコードされた証明書ファイルへのパス
AZURE_CLIENT_CERTIFICATE_PASSWORD	(省略可能) 証明書ファイルのパスワード (存在する場合)
AZURE_CLIENT_SEND_CERTIFICATE_CHAIN	(省略可能) サブジェクト名/発行者ベースの認証をサポートするために、x5c ヘッダーで証明書チェーンを送信する

ユーザー名とパスワード

変数名	価値
AZURE_CLIENT_ID	Microsoft Entra アプリケーションの ID
AZURE_TENANT_ID	アプリケーションの Microsoft Entra テナントの ID
AZURE_USERNAME	ユーザー名 (通常はメール アドレス)
AZURE_PASSWORD	そのユーザーのパスワード

構成は、前の順序で試行されます。 たとえば、クライアント シークレットと証明書の値が両方存在する場合、クライアント シークレットが使用されます。

継続的アクセスの評価

バージョン 3.3.0 以降では、継続的アクセス評価 (CAE) によって保護されたリソースへのアクセスは、要求ごとに可能です。 これは、GetTokenOptions.enableCae(boolean) APIを使用して有効にすることができます。 CAE は、開発者の資格情報ではサポートされていません。

トークン キャッシュ

トークン キャッシュは、アプリが次の操作を可能にする Azure ID ライブラリによって提供される機能です。

• メモリ内およびディスク上のキャッシュ トークン (オプトイン)。
• 回復性とパフォーマンスを向上させます。
• アクセス トークンを取得するために Microsoft Entra ID に対して行われる要求の数を減らします。

Azure Identity ライブラリでは、インメモリ と永続ディスクの両方のキャッシュが提供されます。 詳細については、トークン キャッシュに関するドキュメントを参照してください。

ブローカー認証

認証ブローカーは、ユーザーのコンピューター上で実行され、接続されているアカウントの認証ハンドシェイクとトークンのメンテナンスを管理するアプリケーションです。 現時点では、Windows Web アカウント マネージャー (WAM) のみがサポートされています。 サポートを有効にするには、@azure/identity-broker パッケージを使用します。 WAM を使用した認証の詳細については、ブローカー プラグインのドキュメントを参照してください。

トラブルシューティング

トラブルシューティングに関するサポートについては、トラブルシューティング ガイドを参照してください。

次の手順

ドキュメントを読む

このライブラリの API ドキュメントは、ドキュメント サイトのにあります。

クライアント ライブラリのサポート

Microsoft Entra 認証をサポートする Azure SDK リリース ページ に記載されているクライアント ライブラリと管理ライブラリは、このライブラリからの資格情報を受け入れます。 これらのライブラリの使用の詳細については、リリース ページからリンクされているドキュメントを参照してください。

既知の問題

Azure AD B2C のサポート

このライブラリは、Azure AD B2C サービス をサポートしていません。

その他の未解決の問題については、ライブラリの GitHub リポジトリを参照してください。

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

バグが発生した場合や提案がある場合は、問題開きます。

貢献

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