次の方法で共有

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

  • [アーティクル]

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

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

主要なリンク:

はじめ

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

  • Node.js の LTS バージョンを する
    • 注: Node.js v8 以前でアプリケーションを実行していて、Node.js バージョンを最新の安定したバージョンにアップグレードできない場合は、@azure/identity の依存関係をバージョン 1.1.0 にピン留めします。
  • 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) 直接使用することをお勧めします。 詳細については、次のリンクを参照してください。

  • @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 で認証するには、 ユーザーが Connect-AzAccount コマンドレットを実行できます。 既定では、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 で実行されることを意図しているほとんどのシナリオに適しています。 これは、DefaultAzureCredential は、開発環境での認証に使用される資格情報を使用してデプロイするときに一般的に認証に使用される資格情報を組み合わせたためです。

注: DefaultAzureCredential は、一般的なシナリオを適切な既定の動作で処理することで、SDK の使用を簡略化することを目的としています。 より詳細な制御が必要な開発者、または既定の設定で提供されないシナリオの開発者は、他の資格情報の種類を使用する必要があります。

Node.jsから使用すると、DefaultAzureCredential は次のメカニズムを使用して順番に認証を試みます。

DefaultAzureCredential 認証フロー の

  1. 環境 - DefaultAzureCredential は、環境変数 で指定されたアカウント情報を読み取り、それを使用して認証します。
  2. ワークロード ID - マネージド ID を有効にしてアプリケーションが Azure Kubernetes Service にデプロイされている場合、DefaultAzureCredential はそれに対して認証を行います。
  3. マネージド ID - アプリケーションがマネージド ID が有効になっている Azure ホストにデプロイされている場合、DefaultAzureCredential はそのアカウントで認証されます。
  4. Azure CLI - 開発者が Azure CLI az login コマンドを使用してアカウントを認証した場合、DefaultAzureCredential はそのアカウントで認証されます。
  5. Azure PowerShell - 開発者が Azure PowerShell モジュール Connect-AzAccount コマンドを使用して認証した場合、DefaultAzureCredential はそのアカウントで認証されます。
  6. Azure Developer CLI - 開発者が Azure Developer CLI azd auth login コマンドを使用してアカウントを認証した場合、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 で認証する

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

// 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);

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

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

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

一般に、DefaultAzureCredential は Azure 用アプリケーションの開発を開始する最も簡単な方法ですが、より高度なユーザーは、認証時に考慮される資格情報をカスタマイズする必要があります。 ChainedTokenCredential を使用すると、ユーザーは複数の資格情報インスタンスを組み合わせて、カスタマイズされた資格情報チェーンを定義できます。 この例では、ClientSecretCredentialの異なる 2 つの異なる構成のインスタンスを使用して認証を試み、@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 サービスの 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 { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  }
);

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

資格情報クラス

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

資格 情報 使い 例
DefaultAzureCredential Azure で実行されるアプリケーションの開発を迅速に開始するための簡素化された認証エクスペリエンスを提供します。 例
ChainedTokenCredential ユーザーが複数の資格情報を作成するカスタム認証フローを定義できるようにします。 例
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_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 リポジトリを参照してください。

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

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

貢献

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

インプレッション