Azure Identity Library for Java の資格情報チェーン

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 が資格情報を試行する順序は次のとおりです。

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

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Code omitted for brevity

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .build();

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

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

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

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.IntelliJCredential;
import com.azure.identity.IntelliJCredentialBuilder;

// Code omitted for brevity

AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();
IntelliJCredential ijCredential = new IntelliJCredentialBuilder()
    .build();

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addLast(cliCredential)
    .addLast(ijCredential)
    .build();

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

DefaultAzureCredential の使用ガイド

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

その理由を説明します。

• デバッグが困難: 認証が失敗した場合、問題となっている資格情報のデバッグや特定が困難になることがあります。 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 が成功したので、それ以上の資格情報は試行されませんでした。