.NET 用 Azure Identity ライブラリの資格情報チェーン

[アーティクル]
11/15/2024

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

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

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

資格情報チェーンシーケンス図

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

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

環境認識: アプリが実行されている環境に基づいて、最も適切な資格情報が自動的に選択されます。資格情報チェーンを使用しない場合は、次のようなコードを記述する必要があります。

TokenCredential credential;

if (app.Environment.IsProduction() || app.Environment.IsStaging())
{
    credential = new ManagedIdentityCredential(clientId: userAssignedClientId);
}
else
{
    // local development environment
    credential = new VisualStudioCredential();
}

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

連結する資格情報の選択方法

資格情報の連結には、次のように 2 種類の考え方があります。

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

DefaultAzureCredential の概要

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

DefaultAzureCredential 認証フローチャート

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

注文	資格情報	説明	既定で有効ですか?
1	Environment	environment 変数のコレクションを読み取りアプリケーションサービスプリンシパル (アプリケーションユーザー) がアプリ用に構成されているかどうかを判断します。そうであれば、`DefaultAzureCredential` はこれらの値を使用し、Azure に対してアプリを認証します。この方法は、サーバー環境で最もよく使用されますが、ローカルで開発する場合も使用できます。	はい
2	ワークロード ID	ワークロード ID が有効になっている Azure ホストにアプリがデプロイされている場合は、そのアカウントを認証します。	はい
3	マネージド ID	マネージド ID が有効になっている Azure ホストにアプリがデプロイされている場合は、そのマネージド ID を使用してアプリを Azure に対して認証します。	はい
4	Visual Studio	開発者が Visual Studio にログインして Azure に対する認証を行った場合は、同じアカウントを使用して Azure に対するアプリの認証を行います。	はい
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	対話型ブラウザ	有効であれば、現在のシステムの既定のブラウザーを介し、対話形式で開発者の認証を行います。	いいえ

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

    DefaultAzureCredential credential = new();
    clientBuilder.UseCredential(credential);
});

ヒント

上記のコードスニペットの UseCredential メソッドは、ASP.NET Core アプリで使用することをお勧めします。詳細については、「 ASP.NET Core アプリで Azure SDK for .NET を使用するを参照してください。

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

DefaultAzureCredential から資格情報を削除するには、DefaultAzureCredentialOptions で、対応する Exclude プレフィックス付きのプロパティを使用します。次に例を示します。

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

    clientBuilder.UseCredential(new DefaultAzureCredential(
        new DefaultAzureCredentialOptions
        {
            ExcludeEnvironmentCredential = true,
            ExcludeWorkloadIdentityCredential = true,
            ManagedIdentityClientId = userAssignedClientId,
        }));
});

上のコードサンプルでは、EnvironmentCredential と WorkloadIdentityCredential が資格情報チェーンから削除されます。その結果、最初に試行される資格情報は ManagedIdentityCredential になります。変更されたチェーンは次のようになります。

Excludes プロパティを使用した DefaultAzureCredential

Note

InteractiveBrowserCredential は既定で除外されるため、上の図には示されていません。 InteractiveBrowserCredentialを含めるには、コンストラクターDefaultAzureCredential(Boolean)にtrueを渡すか、プロパティDefaultAzureCredentialOptions.ExcludeInteractiveBrowserCredentialをfalseに設定します。

Exclude プレフィックスの付いたプロパティが true に設定される (資格情報の除外が構成される) 数が多くなるほど、DefaultAzureCredential を使用するメリットが小さくなります。そのような場合は、ChainedTokenCredential を使用する方が適しており、必要なコードも少なくなります。たとえば、次の 2 つのコードサンプルは同じように動作します。

DefaultAzureCredential
ChainedTokenCredential

credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeAzureCliCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
        ManagedIdentityClientId = userAssignedClientId
    });

credential = new ChainedTokenCredential(
    new ManagedIdentityCredential(clientId: userAssignedClientId),
    new VisualStudioCredential());

ChainedTokenCredential の概要

ChainedTokenCredential は、アプリのニーズに合わせて資格情報を追加するための空のチェーンです。次に例を示します。

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new ManagedIdentityCredential(clientId: userAssignedClientId),
        new VisualStudioCredential()));
});

上のコードサンプルでは、2 つの資格情報で構成されるカスタムの資格情報チェーンを作成しています。まず、ManagedIdentityCredential のユーザー割り当てマネージド ID バリアントが試行され、その後で、必要に応じて VisualStudioCredential が試行されます。このチェーンをグラフィカルな形式で示すと、次のようになります。

ChainedTokenCredential

ヒント

パフォーマンスを向上させるには、運用環境に応じて ChainedTokenCredential の資格情報の順序を最適化します。ローカル開発環境での使用を目的とした資格情報は、最後に追加する必要があります。

DefaultAzureCredential の使用ガイド

DefaultAzureCredential は間違いなく、Azure Identity ライブラリを使い始める場合に最も簡単な方法ですが、その便利さにはトレードオフが伴います。アプリを Azure にデプロイしたら、アプリの認証要件を理解する必要があります。そのため、DefaultAzureCredential から次のいずれかのソリューションへの移行の検討を強くお勧めします。

ManagedIdentityCredential など、特定の TokenCredential 実装。オプションについては、派生リストを参照してください。
アプリを実行する Azure 環境向けに最適化されている、簡素化された ChainedTokenCredential 実装。

その理由を説明します。

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

連結された資格情報のデバッグ

予期しない問題を診断したり、チェーンに含まれる資格情報の動作を理解するには、アプリでログ記録を有効化します。必要に応じて、Azure Identity ライブラリから発生したイベントのみにログを絞り込むこともできます。次に例を示します。

using AzureEventSourceListener listener = new((args, message) =>
{
    if (args is { EventSource.Name: "Azure-Identity" })
    {
        Console.WriteLine(message);
    }
}, EventLevel.LogAlways);

たとえば、パラメーターなしの形式の DefaultAzureCredential を使用して Log Analytics ワークスペースへの要求を認証したとします。アプリはローカル開発環境で実行されており、Azure アカウントに対して Visual Studio が認証されています。次にアプリを実行すると、以下のような関連エントリが出力されます。

DefaultAzureCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot
WorkloadIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
WorkloadIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/workloadidentitycredential/troubleshoot
ManagedIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
ManagedIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): ManagedIdentityCredential authentication unavailable. No response received from the managed identity endpoint.
VisualStudioCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
VisualStudioCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00
DefaultAzureCredential credential selected: Azure.Identity.VisualStudioCredential
DefaultAzureCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00

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

EnvironmentCredential、WorkloadIdentityCredential、ManagedIdentityCredential はそれぞれ、この順序で Microsoft Entra アクセストークンの取得に失敗しました。
DefaultAzureCredential credential selected: というプレフィックス付きのエントリは、選択された資格情報 (この場合は VisualStudioCredential) を示します。 VisualStudioCredential が成功したため、それ以降の資格情報は使用されませんでした。

次の方法で共有