JavaScript 用 Azure ID ライブラリの資格情報チェーン

Azure Identity ライブラリは 、資格情報 (Azure Core ライブラリの TokenCredential インターフェイスを実装するパブリッククラス) を提供します。資格情報は、Microsoft Entra ID からアクセストークンを取得するための個別の認証フローを表します。これらの資格情報を連結することにより、試行される一連の認証メカニズムを順序付けたシーケンスを形成できます。

資格情報チェーンのしくみ

実行時に、資格情報チェーンは、シーケンスの最初の資格情報を使用して認証を試みます。その資格情報がアクセストークンの取得に失敗した場合は、アクセストークンが正常に取得されるまで、シーケンス内の次の資格情報が試行されます。次のシーケンス図は、この動作を示しています。

アクセストークンが取得されるまで、認証の試行が複数の資格情報で進行することを示す資格情報チェーンシーケンスの図。

資格情報チェーンを使用する理由

資格情報チェーンの使用には、次の利点があります。

環境認識: アプリが実行されている環境に基づいて、最も適切な資格情報を自動的に選択します。それがなければ、次のようなコードを書く必要があります。

import { 
    ManagedIdentityCredential, 
    AzureCliCredential 
} from "@azure/identity";

let credential;
if (process.env.NODE_ENV === "production") {
    credential = new ManagedIdentityCredential();
} else {
    credential = new AzureCliCredential();
}

シームレスな移行: 認証コードを変更することなく、アプリをローカル開発からステージング環境または運用環境に移行できます。
回復性の向上: 前の認証情報でアクセストークンの取得に失敗すると次の認証情報に移る、フォールバックメカニズムが含まれています。

連結された認証情報を選択する方法

資格情報チェーンには、次の 2 つの異なる方法があります。

チェーンを "分解"する: 構成済みのチェーンから始めて、不要なものを除外します。この方法については、「DefaultAzureCredential の概要」セクションを参照してください。
チェーンを "構築" する: 空のチェーンから始めて、必要なものだけを含めます。この方法については、「ChainedTokenCredential の概要」セクションを参照してください。

DefaultAzureCredential の概要

DefaultAzureCredential は、事前構成済みの資格情報チェーンです。これは、最も一般的な認証フローと開発者ツールと共に、多くの環境をサポートするように設計されています。グラフィカルな形式では、基になるチェーンは次のようになります。

DefaultAzureCredential が資格情報を試行する順序は次のとおりです。

並べ替え	資格情報	説明	既定で有効ですか?
1	環境	環境変数のコレクションを読み取り、アプリケーションサービスプリンシパル (アプリケーションユーザー) がアプリ用に構成されているかどうかを判断します。その場合、`DefaultAzureCredential` はこれらの値を使用して Azure に対してアプリを認証します。この方法は、サーバー環境で最もよく使用されますが、ローカルで開発する場合にも使用できます。	イエス
2	ワークロードアイデンティティ	ワークロード ID が有効になっている Azure ホストにアプリがデプロイされている場合は、そのアカウントを認証します。	イエス
3	マネージド ID	アプリがマネージド ID が有効な Azure ホストにデプロイされている場合は、そのマネージド ID を使用して Azure に対してアプリを認証します。	イエス
4	Visual Studio Code	開発者が Visual Studio Code の Azure リソース拡張機能を使用して認証され、 @azure/identity-vscode パッケージがインストールされている場合は、そのアカウントを認証します。	イエス
5	Azure CLI	開発者が Azure CLI の `az login` コマンドを使用して Azure に対して認証した場合は、同じアカウントを使用して Azure に対してアプリを認証します。	イエス
6	Azure PowerShell	開発者が Azure PowerShell の `Connect-AzAccount` コマンドレットを使用して Azure に対して認証された場合は、同じアカウントを使用して Azure に対してアプリを認証します。	イエス
7	Azure Developer CLI	開発者が Azure Developer CLI の `azd auth login` コマンドを使用して Azure に対して認証された場合は、そのアカウントで認証します。	イエス
8	Broker	ブローカーを介して OS にログインした既定のアカウントを使用して認証します。 @azure/identity-broker パッケージがインストールされている必要があります。	イエス

最も単純な形式では、パラメーターなしのバージョンの DefaultAzureCredential を次のように使用できます。

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

DefaultAzureCredential をカスタマイズする方法

次のセクションでは、チェーンに含める資格情報を制御するための戦略について説明します。

資格情報の種類のカテゴリを除外する

すべての Developer tool または Deployed service 資格情報を除外するには、環境変数の AZURE_TOKEN_CREDENTIALS をそれぞれ prod または devに設定します。 prodの値を使用すると、基になる資格情報チェーンは次のようになります。

アクセストークンが取得されるまで、認証の試行が複数の資格情報で進行することを示す資格情報チェーンシーケンスの図。

devの値を使用すると、チェーンは次のようになります。

AZURE_TOKEN_CREDENTIALSが

環境変数が定義され、サポートされている文字列に設定されていることを確認するには、 requiredEnvVars プロパティを AZURE_TOKEN_CREDENTIALSに設定します。

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

特定の資格情報を使用する

1 つを除くすべての資格情報を除外するには、環境変数 AZURE_TOKEN_CREDENTIALS を資格情報名に設定します。たとえば、DefaultAzureCredentialを AzureCliCredential に設定することで、AZURE_TOKEN_CREDENTIALS チェーンをAzureCliCredentialに減らすことができます。文字列比較は、大文字と小文字を区別せずに実行されます。環境変数の有効な文字列値は次のとおりです。

AzureCliCredential
AzureDeveloperCliCredential
AzurePowerShellCredential
EnvironmentCredential
ManagedIdentityCredential
VisualStudioCodeCredential
WorkloadIdentityCredential

Von Bedeutung

AZURE_TOKEN_CREDENTIALS環境変数は、@azure/identity パッケージバージョン 4.11.0 以降の個々の資格情報名をサポートします。

環境変数が定義され、サポートされている文字列に設定されるようにするには、プロパティ requiredEnvVars を AZURE_TOKEN_CREDENTIALSに設定します。

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

ChainedTokenCredential の概要

ChainedTokenCredential は、アプリのニーズに合わせて資格情報を追加する空のチェーンです。例えば次が挙げられます。

import { 
    ChainedTokenCredential, 
    AzureCliCredential, 
    VisualStudioCodeCredential 
} from "@azure/identity";

const credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new VisualStudioCodeCredential()
);

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

前のコードサンプルでは、2 つの開発時の資格情報で構成されるカスタマイズされた資格情報チェーンを作成します。 AzureCliCredential が最初に試行され、必要に応じて VisualStudioCodeCredentialが続きます。グラフィカルな形式では、チェーンは次のようになります。

AzureCliCredential を最初の試行として、VisualStudioCodeCredential をフォールバックとして示す資格情報チェーンの図。

ヒント

パフォーマンスを向上させるには、ChainedTokenCredential で資格情報の順序を最もよく使用される資格情報から最も少ないものに最適化します。

DefaultAzureCredential の使用ガイダンス

DefaultAzureCredential は間違いなく Azure Identity ライブラリを使い始める最も簡単な方法ですが、その便利さによってトレードオフが生まれます。アプリを Azure にデプロイしたら、アプリの認証要件を理解する必要があります。そのため、DefaultAzureCredential を特定の TokenCredential 実装 (ManagedIdentityCredentialなど) に置き換えます。

その理由は次のとおりです。

デバッグの課題: 認証に失敗した場合、問題のある資格情報をデバッグして特定するのは困難な場合があります。 1 つの資格情報から次の資格情報への進行状況と、それぞれの成功/失敗の状態を確認するには、ログ記録を有効にする必要があります。詳細については、「資格情報のデバッグ」を参照してください。
パフォーマンスのオーバーヘッド: 複数の資格情報を順番に試すプロセスにより、パフォーマンスのオーバーヘッドが発生する可能性があります。たとえば、ローカル開発マシンで実行している場合、マネージド ID は使用できません。そのため、ManagedIdentityCredential は常にローカル開発環境で失敗します。
予測不可能な動作: DefaultAzureCredential では、特定の環境変数の存在確認が行われます。ホストコンピューター上のシステムレベルでこれらの環境変数を追加または変更できる可能性があります。これらの変更はグローバルに適用されるため、そのマシンで実行されているアプリで実行時に DefaultAzureCredential の動作が変更されます。

資格情報をデバッグする

予期しない問題を診断したり、資格情報の動作を理解したりするには、アプリのログ記録を有効にします。例えば次が挙げられます。

import { setLogLevel, AzureLogger } from "@azure/logger";
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

// Constant for the Azure Identity log prefix
const AZURE_IDENTITY_LOG_PREFIX = "azure:identity";

// override logging to output to console.log (default location is stderr)
// only log messages that start with the Azure Identity log prefix
setLogLevel("verbose");
AzureLogger.log = (...args) => {
  const message = args[0];
  if (typeof message === 'string' && message.startsWith(AZURE_IDENTITY_LOG_PREFIX)) {
    console.log(...args);
  }
};

// Get storage account name from environment variable
const storageAccountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!storageAccountName) {
    throw new Error("AZURE_STORAGE_ACCOUNT_NAME environment variable is required");
}

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});


const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

azure:identity:info EnvironmentCredential => Found the following environment variables: 
azure:identity:verbose EnvironmentCredential => AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: undefined; sendCertificateChain: false
azure:identity:info WorkloadIdentityCredential => Found the following environment variables:
azure:identity:warning DefaultAzureCredential => Skipped createDefaultWorkloadIdentityCredential because of an error creating the credential: CredentialUnavailableError: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => Using DefaultToImds managed identity.
azure:identity:warning DefaultAzureCredential => Skipped createDefaultBrokerCredential because of an error creating the credential: Error: Broker for WAM was requested, but no plugin was configured or no authentication record was found. You must install the @azure/identity-broker plugin package (npm install --save @azure/identity-broker) and enable it by importing `useIdentityPlugin` from `@azure/identity` and calling useIdentityPlugin(nativeBrokerPlugin) before using enableBroker.
azure:identity:info DefaultAzureCredential => getToken() => Skipping createDefaultWorkloadIdentityCredential, reason: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => getToken() => Using the MSAL provider for Managed Identity.
azure:identity:info ManagedIdentityCredential - Token Exchange => ManagedIdentityCredential - Token Exchange: Unavailable. The environment variables needed are: AZURE_CLIENT_ID (or the client ID sent through the parameters), AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE
azure:identity:info ManagedIdentityCredential => getToken() => MSAL Identity source: DefaultToImds
azure:identity:info ManagedIdentityCredential => getToken() => Using the IMDS endpoint to probe for availability.
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Pinging the Azure IMDS endpoint
azure:identity:verbose ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Caught error RestError: connect ENETUNREACH 169.254.169.254:80
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: The Azure IMDS endpoint is unavailable
azure:identity:error ManagedIdentityCredential => getToken() => ERROR. Scopes: https://storage.azure.com/.default. Error message: Attempted to use the IMDS endpoint, but it is not available..
azure:identity:info AzureCliCredential => getToken() => Using the scope https://storage.azure.com/.default
azure:identity:info AzureCliCredential => getToken() => expires_on is available and is valid, using it
azure:identity:info AzureCliCredential => getToken() => SUCCESS. Scopes: https://storage.azure.com/.default.

上記の出力では、 DefaultAzureCredential が AzureCliCredentialを使用してトークンを正常に取得していることに注意してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-10