JavaScript 用 Azure Identity クライアント ライブラリ - バージョン 4.1.0
Azure Identity ライブラリは、便利な TokenCredential 実装のセットを通じて、Microsoft Entra ID (旧称 Azure Active Directory) トークン認証を提供します。
さまざまな資格情報の例については、 Azure ID の例に関するページを参照してください。
主要リンク:
作業の開始
v1 から v2 への移行 @azure/identity
の v1 @azure/identityを使用している場合は、v2 に更新するための 移行ガイド を参照してください。
現在サポートされている環境
- Node.js の LTS バージョン
- メモ： アプリケーションが v8 以降 Node.js 実行されていて、Node.js バージョンを最新の安定したバージョンにアップグレードできない場合は、依存関係をバージョン 1.1.0 に固定します
@azure/identity。
- メモ： アプリケーションが v8 以降 Node.js 実行されていて、Node.js バージョンを最新の安定したバージョンにアップグレードできない場合は、依存関係をバージョン 1.1.0 に固定します
- Safari、Chrome、Edge、Firefox の最新バージョン。
- 注: このライブラリでエクスポートされるさまざまな資格情報の中で、
InteractiveBrowserCredentialブラウザーでサポートされている資格情報は 1 つだけです。
- 注: このライブラリでエクスポートされるさまざまな資格情報の中で、
詳細については、Microsoft のサポート ポリシーを参照してください。
パッケージをインストールする
npm を使用して Azure ID をインストールします。
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 のクラスの TokenCredential 実装です。 原則として、 を満たすgetToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>メソッドをgetToken持つオブジェクトは、 としてTokenCredential機能します。 つまり、開発者は、 でカバーされていない認証ケースをサポートするために、独自の資格情報の種類を @azure/identity記述できます。 詳細については、「 カスタム資格情報」を参照してください。
資格情報の種類では多くの高度なケースがサポートされていますが、開発者は認証プロトコルを完全に制御したい場合があります。 そのユース ケースでは、 Microsoft Authentication Library for JavaScript (MSAL.js) を直接使用することをお勧めします。 詳細については、次のリンクを参照してください。
- の高度なユース ケース
@azure/identityの一部を Azure ID の例ページで説明します 。- ここでは、具体的には 「高度な例 」セクションがあります。
- また、 MSAL で直接認証する方法を示すセクションもあります。
ブラウザーでの高度な認証ワークフローの場合は、 @azure/msal-browser ライブラリを直接使用して Azure SDK クライアントを認証する方法を紹介するセクションがあります。
開発環境でクライアントを認証する
運用アプリケーションではマネージド ID またはサービス プリンシパル認証を使用することをお勧めしますが、開発者は、コードをローカルでデバッグして実行するときに、Azure サービスの呼び出しを認証するために独自のアカウントを使用するのが一般的です。 開発環境でこの認証を実行するために使用できる開発者ツールがいくつかあります。
Azure Developer CLIを使用して認証する
IDE の外部でコーディングする開発者は、[Azure Developer CLI][azure_developer_cli] を使用して認証することもできます。 その後、DefaultAzureCredential または AzureDeveloperCliCredential を使用するアプリケーションでこのアカウントを使用して、ローカルでの実行時にアプリケーションの呼び出しを認証できます。
[Azure Developer CLI][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 でブラウザーが起動され、ユーザーが認証されます。
既定の Web ブラウザーがないシステムの場合は、az login コマンドでデバイス コード認証フローを使用します。 ユーザーは、--use-device-code 引数を指定してブラウザーを起動するのではなく、Azure CLI でデバイス コード フローを使用するように強制することもできます。
Azure PowerShellを使用した認証
を使用するAzurePowerShellCredentialアプリケーションでは、 を直接使用するか経由DefaultAzureCredentialするかに関係なく、Azure PowerShellに接続されたアカウントを使用して、ローカルで実行するときにアプリケーションの呼び出しを認証できます。
ユーザー Azure PowerShell認証するには、 コマンドレットをConnect-AzAccount実行します。 既定では、Azure CLI を ike にすると、既定の Web ブラウザーが起動し、 Connect-AzAccount ユーザー アカウントが認証されます。
セッションで対話型認証をサポートできない場合、 -UseDeviceAuthentication 引数は、Azure CLI 資格情報の対応するオプションと同様に、代わりにデバイス コード認証フローを使用するようにコマンドレットを強制します。
Visual Studio Code を使用した認証
Visual Studio Code を使用する開発者は、 Azure アカウント拡張機能 を使用してエディターを介して認証できます。 その後、 を使用する VisualStudioCodeCredential アプリでは、このアカウントを使用して、ローカルで実行するときにアプリで呼び出しを認証できます。
Visual Studio Code で認証するには、Azure アカウント拡張機能がインストールされていることを確認します。 インストールが完了したら、 コマンド パレット を開き、 Azure: Sign In コマンドを実行します。
さらに、プラグイン パッケージを使用します @azure/identity-vscode 。 このパッケージは の依存関係 VisualStudioCodeCredential を提供し、有効にします。 「プラグイン」を参照してください。
これは、0.9.11 より新しい Azure アカウント拡張機能のバージョンでは機能しない既知の問題VisualStudioCodeCredentialです。 この問題に対する長期的な修正が進行中です。 それまでの間は、 Azure CLI を使用した認証を検討してください。
ブラウザーでクライアントを認証する
Web ブラウザー内で Azure SDK クライアントを認証するために、 を提供 InteractiveBrowserCredentialしています。これは、リダイレクトまたはポップアップを使用して認証フローを完了するように設定できます。 まず、Web アプリケーションのAzure portalでAzure アプリ登録を作成する必要があります。
主要な概念
または Microsoft Entra ID を初めて使用@azure/identityする場合は、「using with Microsoft Entra ID first」を参照@azure/identityしてください。 このドキュメントでは、プラットフォームの詳細と、Azure アカウントを正しく構成する方法について説明します。
資格情報
資格情報はクラスの一種であり、サービス クライアントが要求を認証するために必要なデータを格納または取得できます。 Azure SDK 全体のサービス クライアントは、構築時に資格情報を受け入れます。 サービス クライアントは、これらの資格情報を使用してサービスに対する要求を認証します。
Azure Identity ライブラリは、Microsoft Entra IDを使用した OAuth 認証に焦点を当てており、サービス要求を認証するためのMicrosoft Entra トークンを取得できるさまざまな資格情報クラスを提供しています。 このライブラリ内のすべての資格情報クラスは TokenCredential 抽象クラスの実装です。これらはいずれも、TokenCredential で認証できるサービス クライアントの作成に使用できます。
「資格情報クラス」を参照してください。
DefaultAzureCredential
DefaultAzureCredentialは、アプリケーションが最終的に Azure で実行されることを意図しているほとんどのシナリオに適しています。 これは、一般的にデプロイ時の認証に使用される資格情報と、開発環境での認証に使用される資格情報が組み合わせて DefaultAzureCredential に使用されているためです。
注:
DefaultAzureCredentialは、適切な既定の動作で一般的なシナリオを処理することで、SDK の使用を簡略化することを目的としています。 開発者がもっと多くの制御が必要な場合や、シナリオが既定の設定で提供されない場合は、他の資格情報の種類を使用する必要があります。
Node.js から使用すると、 DefaultAzureCredential は次のメカニズムを使用して順番に認証を試みます。
- [環境] - 環境変数
DefaultAzureCredentialで指定されたアカウント情報が読み取られ、認証に使用されます。 - ワークロード ID - マネージド ID が有効になっているAzure Kubernetes Serviceにアプリケーションがデプロイされている場合は、
DefaultAzureCredentialによって認証されます。 - マネージド ID - マネージド ID が 有効になっている Azure ホストにアプリケーションがデプロイされている場合、
DefaultAzureCredentialはそのアカウントで認証されます。 - Azure CLI - 開発者が Azure CLI
az loginコマンドを使用してアカウントを認証した場合、DefaultAzureCredentialはそのアカウントで認証されます。 - Azure PowerShell - 開発者が Azure PowerShell モジュール
Connect-AzAccountコマンドを使用して認証した場合、DefaultAzureCredentialはそのアカウントで認証されます。 - Azure Developer CLI - 開発者が Azure Developer CLI
azd auth loginコマンドを使用してアカウントを認証した場合、DefaultAzureCredentialはそのアカウントで認証されます。
継続ポリシー
バージョン 3.3.0 以降では、 DefaultAzureCredential 以前の開発者資格情報が発生したエラーに関係なく、成功するまで、すべての開発者資格情報で認証が試行されます。 たとえば、開発者の資格情報がトークンの取得を試み、失敗する可能性があるため DefaultAzureCredential 、フロー内の次の資格情報に進みます。 デプロイされたサービス資格情報は、トークンの取得を試みることができるが、受け取らない場合、スローされた例外でフローを停止します。
これにより、デプロイされた動作を予測可能にしながら、コンピューター上のすべての開発者資格情報を試すことができます。
に関する注意 VisualStudioCodeCredential
既知の問題により、 VisualStudioCodeCredential がトークン チェーンからDefaultAzureCredential削除されました。 今後のリリースで問題が解決されると、この変更は元に戻されます。
プラグイン
Azure Identity for JavaScript には、個別のプラグイン パッケージを使用して特定の機能を提供できるプラグイン API が用意 されています。 パッケージは @azure/identity 、プラグインを有効にするために使用できる最上位レベルの関数 (useIdentityPlugin) をエクスポートします。 次の 2 つのプラグイン パッケージを提供します。
@azure/identity-brokerは、Web アカウント マネージャーなどのネイティブ ブローカーを介したブローカー認証のサポートを提供します。@azure/identity-cache-persistenceは、オペレーティング システムによって提供されるネイティブのセキュリティで保護されたストレージ システムを使用して、Node.js での永続的なトークン キャッシュを提供します。 このプラグインを使用すると、キャッシュされたaccess_token値をセッション間で保持できます。つまり、キャッシュされたトークンが使用可能である限り、対話型ログイン フローを繰り返す必要はありません。
例
さまざまな資格情報のその他の使用例については、Azure ID の例のページを参照してください
を使用して認証する DefaultAzureCredential
この例では、 を使用してKeyClient、@azure/keyvault-keys クライアント ライブラリから を認証する方法をDefaultAzureCredential示します。
// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.
// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";
// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";
// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();
// Create authenticated client
const client = new KeyClient(vaultUrl, credential);
を使用してユーザー割り当てマネージド ID を指定します。 DefaultAzureCredential
比較的一般的なシナリオでは、Azure リソースのユーザー割り当てマネージド ID を使用した認証が含まれます。 DefaultAzureCredential を使用したユーザー割り当てマネージド ID の認証に関する記事の例を確認して、環境変数またはコードで構成できる比較的簡単なタスクがどのように行われるかを確認します。
ChainedTokenCredential を使用してカスタム認証フローを定義する
一般に DefaultAzureCredential は Azure 用アプリケーションの開発を開始する最も簡単な方法ですが、より上級のユーザーは、認証時に考慮される資格情報をカスタマイズできます。 ChainedTokenCredential を使用すると、ユーザーは複数の資格情報インスタンスを組み合わせて、カスタマイズされた資格情報チェーンを定義できます。 この例では、 の 2 つの異なる構成のインスタンスClientSecretCredentialを使用して認証を試み、@azure/keyvault-keys から をKeyClient認証する を作成ChainedTokenCredentialする方法を示します。
import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
// 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
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);
マネージド ID のサポート
マネージド ID 認証は、次の Azure サービスに対して、 または ManagedIdentityCredential 資格情報クラスをDefaultAzureCredential介して直接サポートされます。
- Azure App Service と Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Azure Virtual Machines
- Azure 仮想マシン スケール セット
認証にマネージド ID を使用する方法の例については、 例を参照してください。
クラウドの構成
資格情報は、Azure パブリック クラウドのMicrosoft Entra エンドポイントに対する認証に既定で設定されます。 Azure Governmentやプライベート クラウドなど、他のクラウド内のリソースにアクセスするには、コンストラクターの 引数を使用してauthorityHost資格情報を構成します。 インターフェイスは AzureAuthorityHosts 、既知のクラウドの権限を定義します。 米国政府クラウドの場合は、次のように資格情報をインスタンス化できます。
import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
"<YOUR_TENANT_ID>",
"<YOUR_CLIENT_ID>",
"<YOUR_CLIENT_SECRET>",
{
authorityHost: AzureAuthorityHosts.AzureGovernment,
}
);
すべての資格情報でこの構成が必要なわけではありません。 などの AzureCliCredential開発ツールを使用して認証する資格情報は、そのツールの構成を使用します。 同様に、 VisualStudioCodeCredential は引数を authorityHost 受け入れますが、既定値は一致する authorityHost Visual Studio Code の Azure: Cloud 設定です。
資格情報クラス
Azure でホストされるアプリケーションを認証する
| 資格証明 | 使用法 | 例 |
|---|---|---|
DefaultAzureCredential |
Azure で実行されるアプリケーションの開発をすばやく開始するための簡素化された認証エクスペリエンスを提供します。 | 例 |
ChainedTokenCredential |
ユーザーが複数の資格情報で構成されるカスタム認証フローを定義できるようにします。 | 例 |
EnvironmentCredential |
環境変数で指定された資格情報を使用して、サービス プリンシパルまたはユーザーを認証します。 | 例 |
ManagedIdentityCredential |
Azure リソースのマネージド ID を認証します。 | 例 |
WorkloadIdentityCredential |
Kubernetes Microsoft Entraワークロード ID をサポートします。 | 例 |
サービス プリンシパルを認証する
| 資格証明 | 使用法 | 例 | リファレンス |
|---|---|---|---|
ClientAssertionCredential |
署名付きクライアント アサーションを使用してサービス プリンシパルを認証します。 | 例 | サービス プリンシパルの認証 |
ClientCertificateCredential |
証明書を使用してサービス プリンシパルを認証します。 | 例 | サービス プリンシパルの認証 |
ClientSecretCredential |
シークレットを使用してサービス プリンシパルを認証します。 | 例 | サービス プリンシパルの認証 |
ユーザーを認証する
| 資格証明 | 使用法 | 例 | リファレンス |
|---|---|---|---|
AuthorizationCodeCredential |
以前に取得した承認コードを使用してユーザーを認証します。 | 例 | OAuth2 認証コード |
DeviceCodeCredential |
UI が制限されているデバイスでユーザーを対話形式で認証します。 | 例 | デバイス コード認証 |
InteractiveBrowserCredential |
既定のシステム ブラウザーを使用してユーザーを対話形式で認証します。 このしくみの詳細については、こちらを参照してください。 | 例 | OAuth2 認証コード |
OnBehalfOfCredential |
委任されたユーザー ID とアクセス許可を要求チェーンを介して伝達します | 代理認証 | |
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 Account の拡張機能 |
環境変数
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_ID |
Microsoft Entra アプリケーションの ID |
AZURE_TENANT_ID |
アプリケーションのMicrosoft Entra テナントの ID |
AZURE_USERNAME |
ユーザー名 (通常はメール アドレス) |
AZURE_PASSWORD |
そのユーザーのパスワード |
構成は上記の順序で試行されます。 たとえば、クライアント シークレットと証明書の値が両方存在する場合、クライアント シークレットが使用されます。
継続的アクセス評価
バージョン 3.3.0 以降では、 継続的アクセス評価 (CAE) によって保護されたリソースへのアクセスは、要求ごとに可能です。 これは API を使用してGetTokenOptions.enableCae(boolean)有効にすることができます。 CAE は、開発者の資格情報ではサポートされていません。
トークンのキャッシュ
トークン キャッシュは、アプリが次の操作を可能にする Azure Identity ライブラリによって提供される機能です。
- メモリ内およびディスク上のキャッシュ トークン (オプトイン)。
- 回復性とパフォーマンスを向上させます。
- アクセス トークンを取得するためにMicrosoft Entra IDに対して行われる要求の数を減らします。
Azure Identity ライブラリには、メモリ内と永続的なディスク キャッシュの両方が用意されています。 詳細については、 トークン キャッシュに関するドキュメントを参照してください。
ブローカー認証
認証ブローカーは、ユーザーのコンピューター上で実行され、接続されているアカウントの認証ハンドシェイクとトークンのメンテナンスを管理するアプリケーションです。 現時点では、Windows Web アカウント マネージャー (WAM) のみがサポートされています。 サポートを有効にするには、 パッケージを使用します @azure/identity-broker 。 WAM を使用した認証の詳細については、 ブローカー プラグインのドキュメントを参照してください。
トラブルシューティング
トラブルシューティングに関するサポートについては、トラブルシューティング ガイドを参照してください。
次のステップ
ドキュメントを読む
このライブラリの API ドキュメントは、ドキュメント サイトにあります。
クライアント ライブラリのサポート
Microsoft Entra認証をサポートする Azure SDK リリース ページに記載されているクライアントライブラリと管理ライブラリは、このライブラリからの資格情報を受け入れます。 これらのライブラリの使用方法の詳細については、リリース ページからリンクされているドキュメントを参照してください。
既知の問題
Azure AD B2C でのサポート
このライブラリでは、 Azure AD B2C サービスはサポートされていません。
その他の未解決の問題については、ライブラリの GitHub リポジトリを参照してください。
フィードバックの提供
バグが発生した場合や提案がある場合は、issue をオープンしてください。
共同作成
このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。
Azure SDK for JavaScript
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示