Java 用 Azure Identity クライアント ライブラリの資格情報チェーン
Azure Identity クライアント ライブラリは、Azure Core ライブラリの TokenCredential インターフェイスを実装する資格情報 (パブリック クラス) を提供します。 資格情報は、Microsoft Entra ID からアクセス トークンを取得するための個別の認証フローを表します。 これらの資格情報を連結することにより、試行される一連の認証メカニズムを順序付けたシーケンスを形成できます。
資格情報チェーンのしくみ
資格情報チェーンでは、実行時に、シーケンスの最初の資格情報を使用した認証が試行されます。 その資格情報がアクセス トークンの取得に失敗した場合は、シーケンス内の次の資格情報が試みられ、正常にアクセス トークンが取得されるまでそれを続けます。 次のシーケンス図はこの動作を示しています。
資格情報チェーンを使用する理由
資格情報チェーンの使用には、次の利点があります。
環境認識: アプリが実行されている環境に基づいて、最も適切な資格情報が自動的に選択されます。 資格情報チェーンを使用しない場合は、次のようなコードを記述する必要があります。
import com.azure.core.credential.TokenCredential; import com.azure.identity.AzureCliCredentialBuilder; import com.azure.identity.ManagedIdentityCredentialBuilder; // Code omitted for brevity TokenCredential credential = null; // Set up credential based on environment (Azure or local development) String environment = System.getenv("ENV"); if (environment != null && environment.equals("production")) { credential = new ManagedIdentityCredentialBuilder() .clientId(userAssignedClientId) .build(); } else { credential = new AzureCliCredentialBuilder() .build(); }シームレスな移行: 認証コードを変更することなく、アプリをローカル開発からステージング環境または運用環境に移行できます。
回復性の向上: 前の認証情報でアクセス トークンの取得に失敗すると次の認証情報に移る、フォールバック メカニズムが含まれています。
連結する資格情報の選択方法
資格情報の連結には、次のように 2 種類の考え方があります。
- 事前構成済みチェーンを使用する: 最も一般的な認証シナリオに対応する、オピニオン化され、事前構築されたチェーンから始めます。 この方法については、「DefaultAzureCredential の概要」セクションを参照してください。
- チェーンを "構築" する: 空のチェーンから始めて、必要なものだけを含めます。 この方法については、「ChainedTokenCredential の概要」セクションを参照してください。
DefaultAzureCredential の概要
DefaultAzureCredential は、事前構成済みの資格情報チェーンです。 これは、最も一般的な認証フローおよび開発者ツールのほか、多くの環境をサポートするように設計されています。 基になるチェーンをグラフィカルな形式で示すと、次のようになります。
DefaultAzureCredential が資格情報を試行する順序は次のとおりです。
| 注文 | 資格情報 | 説明 |
|---|---|---|
| 1 | Environment | environment 変数のコレクションを読み取りアプリケーション サービス プリンシパル (アプリケーション ユーザー) がアプリ用に構成されているかどうかを判断します。 そうであれば、DefaultAzureCredential はこれらの値を使用し、Azure に対してアプリを認証します。 この方法は、サーバー環境で最もよく使用されますが、ローカルで開発する場合も使用できます。 |
| 2 | ワークロード ID | ワークロード ID が有効になっている Azure ホストにアプリがデプロイされている場合は、そのアカウントを認証します。 |
| 3 | マネージド ID | マネージド ID が有効になっている Azure ホストにアプリがデプロイされている場合は、そのマネージド ID を使用してアプリを Azure に対して認証します。 |
| 4 | 共有トークン キャッシュ | 開発者が Visual Studio にログインして Azure に対する認証を行った場合は、同じアカウントを使用して Azure に対するアプリの認証を行います。 (Windows のみ。) |
| 5 | IntelliJ | 開発者が Azure Toolkit for IntelliJ を使用して認証された場合は、そのアカウントを認証します。 |
| 6 | Azure CLI | 開発者が Azure CLI の az login コマンドを使用して Azure に対する認証を行った場合は、その同じアカウントを使用して Azure に対するアプリの認証を行います。 |
| 7 | Azure PowerShell | 開発者が Azure PowerShell の Connect-AzAccount コマンドレットを使用して Azure に対する認証を行った場合は、その同じアカウントを使用して Azure に対するアプリの認証を行います。 |
| 8 | Azure Developer CLI | 開発者が Azure Developer CLI の azd auth login コマンドを使用して Azure に対する認証を行った場合は、そのアカウントで認証を行います。 |
DefaultAzureCredential は、最も単純な形式として次のようにパラメーターなしのバージョンを使用することもできます。
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
// Code omitted for brevity
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
.build();
ChainedTokenCredential の概要
ChainedTokenCredential は、アプリのニーズに合わせて資格情報を追加するための空のチェーンです。 次に例を示します。
import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;
import com.azure.identity.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;
// Code omitted for brevity
ManagedIdentityCredential miCredential = new ManagedIdentityCredentialBuilder()
.clientId(userAssignedClientId)
.build();
AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
.build();
ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
.addLast(miCredential)
.addLast(cliCredential)
.build();
上のコード サンプルでは、2 つの資格情報で構成されるカスタムの資格情報チェーンを作成しています。 まず、ManagedIdentityCredential のユーザー割り当てマネージド ID バリアントが試行され、その後で、必要に応じて AzureCliCredential が試行されます。 このチェーンをグラフィカルな形式で示すと、次のようになります。
ヒント
パフォーマンスを向上させるには、運用環境に応じて ChainedTokenCredential の資格情報の順序を最適化します。 ローカル開発環境での使用を目的とした資格情報は、最後に追加する必要があります。
DefaultAzureCredential の使用ガイド
DefaultAzureCredential は間違いなく、もっとも簡単に Azure Identity ライブラリを使い始められる方法ですが、その便利さにはトレードオフが伴います。 アプリを Azure にデプロイしたら、アプリの認証要件を理解する必要があります。 そのため、DefaultAzureCredential から次のいずれかのソリューションへの移行の検討を強くお勧めします。
ManagedIdentityCredentialなど、特定の資格情報実装。- アプリを実行する Azure 環境向けに最適化されている、簡素化された
ChainedTokenCredential実装。
その理由を説明します。
- デバッグが困難: 認証が失敗した場合、問題となっている資格情報のデバッグや特定が困難になることがあります。 1 つの資格情報から次の資格情報への進行状況や、それぞれの成功/失敗の状態を確認するには、ログ記録を有効にする必要があります。 詳細については、「連結された資格情報のデバッグ」を参照してください。
- パフォーマンスのオーバーヘッド: 複数の資格情報を順番に試すプロセスにより、パフォーマンスのオーバーヘッドが発生する可能性があります。 たとえば、ローカル開発マシンでの実行時に、マネージド ID は使用できません。 そのため、
ManagedIdentityCredentialは常にローカル開発環境で失敗します。 - 予測不可能な動作:
DefaultAzureCredentialでは、特定の環境変数の存在確認が行われます。 ホスト マシン上のシステム レベルでは、これらの環境変数の追加または変更が行われる可能性があります。 このような変更はグローバルに適用されるため、そのマシンで実行されているアプリで、DefaultAzureCredentialのランタイム動作が変更されます。
連結された資格情報のデバッグ
予期しない問題を診断したり、チェーンに含まれる資格情報の動作を理解するには、アプリでログ記録を有効化します。
たとえば、パラメーターなしの形式の DefaultAzureCredential を使用して Blob Storage アカウントへの要求を認証したとします。 アプリはローカル開発環境で実行され、開発者は Azure CLI を使用して Azure に認証されます。 アプリを実行すると、次の関連するエントリが出力に表示されます。
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential EnvironmentCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential WorkloadIdentityCredential is unavailable.
[ForkJoinPool.commonPool-worker-1] WARN com.microsoft.aad.msal4j.ConfidentialClientApplication - [Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd] Execution of class com.microsoft.aad.msal4j.AcquireTokenByClientCredentialSupplier failed: java.util.concurrent.ExecutionException: com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential ManagedIdentityCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential SharedTokenCacheCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token
上の出力では、次のことがわかります。
EnvironmentCredential、WorkloadIdentityCredential、ManagedIdentityCredential、SharedTokenCacheCredentialおよびIntelliJCredentialはそれぞれ、この順序で Microsoft Entra アクセス トークンの取得に失敗しました。AzureCliCredential.getTokenの呼び出しは、returns a tokenサフィックス付きエントリで示されているように成功します。AzureCliCredentialが成功したため、それ以降の資格情報は試行されませんでした。