JavaのAzure ID ライブラリ内の資格情報チェーン

Azure ID ライブラリには、Azure Core ライブラリの TokenCredential> インターフェイスを実装する credentials パブリック クラスが用意されています。 資格情報は、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 認証フローを示す図。

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

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

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

// Code omitted for brevity

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

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

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

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

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

AZURE_TOKEN_CREDENTIALSが "prod" に設定された DefaultAzureCredential を示す図。

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

AZURE_TOKEN_CREDENTIALSが 'dev' に設定された DefaultAzureCredential を示す図。

環境変数が定義され、サポートされている文字列に設定されていることを確認するには、メソッドを次のように 呼び出します。

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

既定の の代わりにカスタム環境変数名を使用するには、 を使用してカスタム変数への参照を作成します。

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.fromString("MY_CUSTOM_TOKEN_CREDENTIALS"))
    .build();

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

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

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• IntelliJCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

環境変数が定義され、サポートされている文字列に設定されていることを確認するには、次のように requireEnvVars メソッドを 呼び出します。

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .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.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 つの開発時の資格情報で構成されるカスタマイズされた資格情報チェーンを作成します。 が最初に試行され、必要に応じて が続きます。 このチェーンをグラフィカルな形式で示すと、次のようになります。

DefaultAzureCredential の使用ガイド

DefaultAzureCredentialは間違いなくAzure IDENTITY ライブラリを使い始める最も簡単な方法ですが、その利便性にはトレードオフがあります。 アプリをAzureにデプロイした後は、アプリの認証要件を理解し、DefaultAzureCredentialがシナリオに適しているかどうかを検討する必要があります。

には重要な利点があります。アプリケーション コードを特定の認証メカニズムから切り離すことで、コードを変更せずに認証構成を変更できます。 運用環境の認証を意識的に構成する経験豊富な開発者にとって、この柔軟性は価値があります。 ただし、この柔軟性には潜在的な欠点があります。

• デバッグが困難: 認証が失敗した場合、問題となっている資格情報のデバッグや特定が困難になることがあります。 1 つの資格情報から次の資格情報への進行状況や、それぞれの成功/失敗の状態を確認するには、ログ記録を有効にする必要があります。 詳細については、「連結された資格情報のデバッグ」を参照してください。
• パフォーマンスのオーバーヘッド: 複数の資格情報を順番に試すプロセスにより、パフォーマンスのオーバーヘッドが発生する可能性があります。 たとえば、ローカル開発マシンでの実行時に、マネージド ID は使用できません。 そのため、 は常にローカル開発環境で失敗します。
• 予測不可能な動作: DefaultAzureCredential は、特定のenvironment 変数が存在するかどうかチェックします。 ホスト マシン上のシステム レベルでは、これらの環境変数の追加または変更が行われる可能性があります。 このような変更はグローバルに適用されるため、そのマシンで実行されているアプリで、 のランタイム動作が変更されます。
• アクセス許可の不一致: は、その資格情報に適切なアクセス許可があるかどうかに関係なく、トークンを正常に取得した最初の資格情報で停止します。 たとえば、ローカル開発資格情報に運用マネージド ID よりも広範なアクセス許可がある場合、アプリはローカルで動作しますが、デプロイ後の承認チェックは失敗します。

チェーン化された資格情報のデバッグ

予期しない問題を診断したり、チェーンに含まれる資格情報の動作を理解するには、アプリでログ記録を有効化します。

説明のために、パラメーターなしの形式の 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 IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential VisualStudioCodeCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token

上の出力では、次のことがわかります。

• EnvironmentCredential、WorkloadIdentityCredential、ManagedIdentityCredential、IntelliJCredential、および VisualStudioCodeCredential は、それぞれその順序でMicrosoft Entraアクセス トークンを取得できませんでした。
• の呼び出しは、 サフィックス付きエントリで示されているように成功します。 が成功したので、それ以上の資格情報は試行されませんでした。