.NET 用 Azure Identity クライアント ライブラリ - バージョン 1.10.3
Azure Identity ライブラリは、Azure SDK 全体でMicrosoft Entra ID (旧称 Azure Active Directory) トークン認証のサポートを提供します。 トークン認証をサポートする Azure SDK クライアントをTokenCredential構築するために使用できる一連の実装Microsoft Entra提供されます。
ソースコード | パッケージ (NuGet) | API リファレンス ドキュメント | Microsoft Entra ID のドキュメント
作業の開始
パッケージをインストールする
NuGet を使用して .NET 用 Azure Identity クライアント ライブラリをインストールします。
dotnet add package Azure.Identity
前提条件
- Azure サブスクリプション。
- Azure CLI は、開発環境での認証、アカウントの作成、アカウント ロールの管理にも役立ちます。
クライアントを認証する
コードをローカルでデバッグして実行する場合、開発者は独自のアカウントを使用して Azure サービスへの呼び出しを認証するのが一般的です。 開発環境でこの認証を実行するために使用できる開発者ツールがいくつかあります。
Visual Studio を使用した認証
Visual Studio 2017 以降を使用する開発者は、IDE を使用してMicrosoft Entra アカウントを認証できます。 その後、DefaultAzureCredential または VisualStudioCredential を使用するアプリケーションでこのアカウントを使用して、ローカルでの実行時にアプリケーションの呼び出しを認証できます。
Visual Studio で認証するには、[ ツール>オプション] メニューを選択して [オプション] ダイアログを起動します。 次に、Azure Service AuthenticationMicrosoft Entra アカウントでサインインするためのオプションに移動します。
Visual Studio Code を使用した認証
Visual Studio Code を使用する開発者は、 Azure アカウント拡張機能 を使用してエディターを介して認証できます。 その後、DefaultAzureCredential または VisualStudioCodeCredential を使用するアプリケーションでこのアカウントを使用して、ローカルでの実行時にアプリケーションの呼び出しを認証できます。
これは、0.9.11 より新しい Azure アカウント拡張機能のバージョンでは機能しない既知の問題VisualStudioCodeCredentialです。 この問題に対する長期的な修正が進行中です。 それまでの間は、 Azure CLI を使用した認証を検討してください。
Azure CLI を使用した認証
IDE の外部でコーディングする開発者は、 Azure CLI を使用して認証することもできます。 その後、DefaultAzureCredential または AzureCliCredential を使用するアプリケーションでこのアカウントを使用して、ローカルでの実行時にアプリケーションの呼び出しを認証できます。
Azure CLI で認証を行うために、ユーザーは コマンド az loginを実行できます。 既定の Web ブラウザーを使用してシステムで実行されているユーザーの場合、Azure CLI によってブラウザーが起動され、ユーザーが認証されます。
既定の Web ブラウザーがないシステムの場合は、az login コマンドでデバイス コード認証フローを使用します。 ユーザーは、--use-device-code 引数を指定してブラウザーを起動するのではなく、Azure CLI でデバイス コード フローを使用するように強制することもできます。
Azure Developer CLIを使用して認証する
IDE の外部でコーディングする開発者は、Azure Developer CLIを使用して認証することもできます。 その後、DefaultAzureCredential または AzureDeveloperCliCredential を使用するアプリケーションでこのアカウントを使用して、ローカルでの実行時にアプリケーションの呼び出しを認証できます。
Azure Developer CLIで認証を行うために、ユーザーは コマンド azd auth loginを実行できます。 既定の Web ブラウザーを使用してシステムで実行されているユーザーの場合、Azure Developer CLIはブラウザーを起動してユーザーを認証します。
既定の Web ブラウザーがないシステムの場合は、azd auth login --use-device-code コマンドでデバイス コード認証フローを使用します。
Azure PowerShellを使用した認証
IDE の外部でコーディングする開発者は、Azure PowerShellを使用して認証することもできます。 その後、DefaultAzureCredential または AzurePowerShellCredential を使用するアプリケーションでこのアカウントを使用して、ローカルでの実行時にアプリケーションの呼び出しを認証できます。
Azure PowerShellで認証を行うために、ユーザーは コマンド Connect-AzAccountを実行できます。 既定の Web ブラウザーとバージョン 5.0.0 以降の azure PowerShell を使用してシステム上で実行されているユーザーの場合は、ブラウザーを起動してユーザーを認証します。
既定の Web ブラウザーがないシステムの場合は、Connect-AzAccount コマンドでデバイス コード認証フローを使用します。 ユーザーは、 引数を指定してブラウザーを起動するのではなく、Azure PowerShellにデバイス コード フローを強制的にUseDeviceAuthentication使用することもできます。
主要な概念
資格情報
資格情報はクラスの一種であり、サービス クライアントが要求を認証するために必要なデータを格納または取得できます。 Azure SDK 全体のサービス クライアントは、構築時に資格情報を受け入れます。 サービス クライアントは、これらの資格情報を使用してサービスに対する要求を認証します。
Azure Identity ライブラリは、Microsoft Entra ID を使用した OAuth 認証に焦点を当てており、サービス要求を認証するためのMicrosoft Entra トークンを取得できるさまざまな資格情報クラスを提供しています。 このライブラリ内のすべての資格情報クラスは、Azure.Core の抽象クラスのTokenCredential実装であり、それらのいずれかを使用して、 でTokenCredential認証できるサービス クライアントを構築できます。
使用可能な資格情報の種類の完全な一覧については、「資格情報 クラス 」を参照してください。
DefaultAzureCredential
DefaultAzureCredentialは、アプリケーションが最終的に Azure で実行されることを意図しているほとんどのシナリオに適しています。 これは、一般的にデプロイ時の認証に使用される資格情報と、開発環境での認証に使用される資格情報が組み合わせて DefaultAzureCredential に使用されているためです。
注:
DefaultAzureCredentialは、適切な既定の動作で一般的なシナリオを処理することで、SDK の使用を簡略化することを目的としています。 開発者がもっと多くの制御が必要な場合や、シナリオが既定の設定で提供されない場合は、他の資格情報の種類を使用する必要があります。
は DefaultAzureCredential 、次のメカニズムを使用して認証を試みます。この順序で、成功すると停止します。
- 環境 - 環境変数
DefaultAzureCredentialで指定されたアカウント情報が読み取られ、認証に使用されます。 - ワークロード ID - ワークロード ID が 有効になっている Azure ホストにアプリケーションがデプロイされている場合、
DefaultAzureCredentialはそのアカウントで認証されます。 - マネージド ID - アプリケーションがマネージド ID が有効な Azure ホストにデプロイされている場合、
DefaultAzureCredentialはそのアカウントで認証されます。 - Visual Studio - 開発者が Visual Studio 経由で認証した場合、
DefaultAzureCredentialはそのアカウントで認証されます。 - Visual Studio Code - 現在、Visual Studio Code 経由の SDK 認証は問題 #27263 のために壊れているため、既定では除外されています。
VisualStudioCodeCredential修正プログラムが設定されると、DefaultAzureCredentialフローで が再び有効になります。 問題 #30525 はこれを追跡します。 それまでの間、Visual Studio Code ユーザーは Azure CLI を使用して開発環境を認証できます。 - Azure CLI - 開発者が Azure CLI
az loginコマンドを使用してアカウントを認証した場合、DefaultAzureCredentialはそのアカウントで認証されます。 - Azure PowerShell - 開発者が Azure PowerShell
Connect-AzAccountコマンドを使用してアカウントを認証した場合、DefaultAzureCredentialはそのアカウントで認証されます。 - Azure Developer CLI - 開発者が Azure Developer CLI
azd auth loginコマンドを使用して認証した場合、DefaultAzureCredentialはそのアカウントで認証されます。 - 対話型ブラウザー - 有効にすると、
DefaultAzureCredentialは現在のシステムの既定のブラウザーを介して開発者を対話形式で認証します。 既定では、この資格情報の種類は無効になっています。
継続ポリシー
バージョン 1.10.1 以降では、 DefaultAzureCredential 以前に発生した開発者資格情報のエラーに関係なく、成功するまで、すべての開発者資格情報で認証が試行されます。 たとえば、開発者の資格情報がトークンの取得を試み、失敗する可能性があるため DefaultAzureCredential 、フロー内の次の資格情報に進みます。 デプロイされたサービス資格情報は、トークンの取得を試みることができるが、受け取らない場合、スローされた例外でフローを停止します。 バージョン 1.10.1 より前のバージョンでは、開発者の資格情報も同様に、トークンの取得に失敗した場合に認証フローを停止します。
この動作により、予測可能なデプロイ動作を行いながら、コンピューター上のすべての開発者資格情報を試すことができます。
例
で認証する DefaultAzureCredential
この例では、 を使用して SecretClientAzure.Security.KeyVault.Secrets クライアント ライブラリから を認証する方法を DefaultAzureCredential示します。
// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());
を使用して対話型認証を有効にする DefaultAzureCredential
既定では、対話型認証は 無効になっています DefaultAzureCredential 。 この例では、 の対話型認証部分を有効にする 2 つの方法を DefaultAzureCredential示します。 有効にすると、 DefaultAzureCredential は、他の資格情報が使用できない場合、システムの既定のブラウザーを介して開発者を対話形式で認証することにフォールバックします。 次に、対話型認証がEventHubProducerClient有効になっている を使用してDefaultAzureCredential、Azure.Messaging.EventHubs クライアント ライブラリの を認証します。
// the includeInteractiveCredentials constructor parameter can be used to enable interactive authentication
var credential = new DefaultAzureCredential(includeInteractiveCredentials: true);
var eventHubClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);
でユーザー割り当てマネージド ID を指定する DefaultAzureCredential
多くの Azure ホストでは、ユーザー割り当てマネージド ID を割り当てることができます。 この例では、 を構成 DefaultAzureCredential して、Azure ホストにデプロイするときにユーザー割り当て ID を認証する方法を示します。 その後、資格情報を BlobClient 使用して Azure.Storage.Blobs クライアント ライブラリから を認証します。
// When deployed to an azure host, the default azure credential will authenticate the specified user assigned managed identity.
string userAssignedClientId = "<your managed identity client Id>";
var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });
var blobClient = new BlobClient(new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"), credential);
コード経由で を ManagedIdentityClientId 構成するだけでなく、 環境変数を AZURE_CLIENT_ID 使用して設定することもできます。 これら 2 つの方法は、 を使用する場合と同等です DefaultAzureCredential。
を使用してカスタム認証フローを定義する ChainedTokenCredential
一般に DefaultAzureCredential は Azure 用アプリケーションの開発を開始する最も簡単な方法ですが、より上級のユーザーは、認証時に考慮される資格情報をカスタマイズできます。 ChainedTokenCredential を使用すると、ユーザーは複数の資格情報インスタンスを組み合わせて、カスタマイズされた資格情報チェーンを定義できます。 この例では、 を作成し ChainedTokenCredential 、マネージド ID を使用して認証を試み、現在の環境でマネージド ID が使用できない場合は Azure CLI を介した認証にフォールバックします。 その後、資格情報は、Azure.Messaging.EventHubs クライアント ライブラリからの をEventHubProducerClient認証するために使用されます。
// Authenticate using managed identity if it is available; otherwise use the Azure CLI to authenticate.
var credential = new ChainedTokenCredential(new ManagedIdentityCredential(), new AzureCliCredential());
var eventHubProducerClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);
マネージド ID のサポート
マネージド ID 認証 は、次の Azure サービスの または DefaultAzureCredential を ManagedIdentityCredential 介して直接サポートされます。
- Azure App Service と Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Azure Virtual Machines
- Azure 仮想マシン スケール セット
例
これらの例では、 を使用して SecretClientAzure.Security.KeyVault.Secrets クライアント ライブラリから を認証する方法を ManagedIdentityCredential示します。
ユーザー割り当てマネージド ID で認証する
var credential = new ManagedIdentityCredential(clientId: userAssignedClientId);
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);
システム割り当てマネージド ID で認証する
var credential = new ManagedIdentityCredential();
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);
クラウドの構成
資格情報の既定値は、Azure パブリック クラウドのMicrosoft Entra エンドポイントに対する認証です。 Azure Governmentやプライベート クラウドなど、他のクラウド内のリソースにアクセスするには、 引数を使用して資格情報をAuthorityHost構成します。 AzureAuthorityHosts は、 既知のクラウドの機関を定義します。
var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { AuthorityHost = AzureAuthorityHosts.AzureGovernment });
すべての資格情報でこの構成が必要なわけではありません。 などの AzureCliCredential開発ツールを使用して認証する資格情報は、そのツールの構成を使用します。
資格情報クラス
Azure でホストされるアプリケーションを認証する
| 資格証明 | 使用 |
|---|---|
DefaultAzureCredential |
Azure で実行されるアプリケーションの開発を迅速に開始するための簡素化された認証エクスペリエンスを提供します。 |
ChainedTokenCredential |
ユーザーが複数の資格情報で構成されるカスタム認証フローを定義できるようにします。 |
EnvironmentCredential |
環境変数で指定された資格情報を使用して、サービス プリンシパルまたはユーザーを認証します。 |
ManagedIdentityCredential |
Azure リソースのマネージド ID を認証します。 |
WorkloadIdentityCredential |
Kubernetes でのMicrosoft Entra ワークロード IDをサポートします。 |
サービス プリンシパルを認証する
| 資格証明 | 使用 | リファレンス |
|---|---|---|
ClientAssertionCredential |
署名されたクライアント アサーションを使用してサービス プリンシパルを認証します。 | |
ClientCertificateCredential |
証明書を使用してサービス プリンシパルを認証します。 | サービス プリンシパルの認証 |
ClientSecretCredential |
シークレットを使用してサービス プリンシパルを認証します。 | サービス プリンシパルの認証 |
ユーザーを認証する
| 資格証明 | 使用 | リファレンス |
|---|---|---|
AuthorizationCodeCredential |
以前に取得した承認コードを使用してユーザーを認証します。 | OAuth2 認証コード |
DeviceCodeCredential |
UI が制限されているデバイスでユーザーを対話形式で認証します。 | デバイス コード認証 |
InteractiveBrowserCredential |
既定のシステム ブラウザーを使用してユーザーを対話形式で認証します。 | OAuth2 認証コード |
OnBehalfOfCredential |
委任されたユーザー ID とアクセス許可を要求チェーンを介して伝達します。 | 代理認証 |
UsernamePasswordCredential |
ユーザー名とパスワードを使用してユーザーを認証します。 | ユーザー名とパスワードによる認証 |
開発ツールを使用した認証
| 資格証明 | 使用 | リファレンス |
|---|---|---|
AzureCliCredential |
Azure CLI を使用して開発環境で認証します。 | Azure CLI 認証 |
AzureDeveloperCliCredential |
Azure Developer CLIを使用して開発環境で認証します。 | Azure Developer CLI リファレンス |
AzurePowerShellCredential |
Azure PowerShellを使用して開発環境で認証します。 | Azure PowerShell認証 |
VisualStudioCredential |
Visual Studio を使用して開発環境で認証を行います。 | Visual Studio の構成 |
VisualStudioCodeCredential |
Visual Studio Code Azure アカウント拡張機能にサインインしたユーザーとして認証します。 | VS Code Azure Account の拡張機能 |
メモ： Azure Identity ライブラリ内のすべての資格情報の実装はスレッド セーフであり、1 つの資格情報インスタンスを複数のサービス クライアントで使用できます。
環境変数
DefaultAzureCredential と EnvironmentCredential は環境変数を使用して構成できます。 認証の種類ごとに、特定の変数の値が必要です。
シークレットを持つサービス プリンシパル
| 変数名 | 値 |
|---|---|
AZURE_CLIENT_ID |
Microsoft Entra アプリケーションの ID |
AZURE_TENANT_ID |
アプリケーションのMicrosoft Entra テナントの ID |
AZURE_CLIENT_SECRET |
アプリケーションのクライアント シークレットの 1 つ |
証明書を使用したサービス プリンシパル
| 変数名 | 値 |
|---|---|
AZURE_CLIENT_ID |
Microsoft Entra アプリケーションの ID |
AZURE_TENANT_ID |
アプリケーションのMicrosoft Entra テナントの ID |
AZURE_CLIENT_CERTIFICATE_PATH |
秘密キーを含む PFX または PEM でエンコードされた証明書ファイルへのパス |
AZURE_CLIENT_CERTIFICATE_PASSWORD |
(省略可能) 証明書ファイルを保護するパスワード (現在、PFX (PKCS12) 証明書でのみサポートされています) |
AZURE_CLIENT_SEND_CERTIFICATE_CHAIN |
(省略可能) サブジェクト名/発行者ベースの認証をサポートするために、x5c ヘッダーで証明書チェーンを送信する |
ユーザー名とパスワード
| 変数名 | 値 |
|---|---|
AZURE_CLIENT_ID |
Microsoft Entra アプリケーションの ID |
AZURE_TENANT_ID |
アプリケーションのMicrosoft Entra テナントの ID |
AZURE_USERNAME |
ユーザー名 (通常はメール アドレス) |
AZURE_PASSWORD |
そのユーザーのパスワード |
構成は上記の順序で試行されます。 たとえば、クライアント シークレットと証明書の値が両方存在する場合、クライアント シークレットが使用されます。
継続的アクセス評価
バージョン 1.10.0 以降では、 継続的アクセス評価 (CAE) によって保護されたリソースへのアクセスは、要求ごとに可能です。 この動作を有効にするには、コンストラクターを使用して の IsCaeEnabledTokenRequestContext プロパティを設定します。 CAE は、開発者とマネージド ID の資格情報ではサポートされていません。
トークンのキャッシュ
トークン キャッシュは、アプリが次の操作を可能にする Azure Identity ライブラリによって提供される機能です。
- メモリ内またはディスク (オプトイン) にトークンをキャッシュします。
- 回復性とパフォーマンスを向上させます。
- アクセス トークンを取得するために ID をMicrosoft Entraする要求の数を減らします。
Azure Identity ライブラリには、メモリ内と永続的なディスク キャッシュの両方が用意されています。 詳細については、トークン キャッシュに関するドキュメントを参照してください。
トラブルシューティング
さまざまな障害シナリオを診断する方法の詳細については、 トラブルシューティング ガイド を参照してください。
エラー処理
認証に起因するエラーは、サービスに対する要求を行う任意のサービス クライアントメソッドで発生する可能性があります。 これは、資格情報からトークンが初めて要求されるときがサービスの最初の呼び出しであり、後続の呼び出しでトークンを更新する必要がある可能性があるためです。 これらのエラーをサービス クライアントの Azure Identity クラスのエラーと区別するために、 AuthenticationFailedException 例外メッセージのエラーの原因と、場合によってはエラー メッセージに詳細を付けて を発生させます。 アプリケーションによっては、これらのエラーが回復可能な場合とそうでない場合があります。
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());
try
{
KeyVaultSecret secret = await client.GetSecretAsync("secret1");
}
catch (AuthenticationFailedException e)
{
Console.WriteLine($"Authentication Failed. {e.Message}");
}
MICROSOFT ENTRA ID またはマネージド ID エンドポイントへの要求の失敗に起因するエラーの対処の詳細については、承認エラー コードに関するMicrosoft Entra ID ドキュメントを参照してください。
ログ記録
Azure Identity ライブラリには、Azure SDK の残りの部分と同じ ログ機能 が用意されています。
認証の問題をデバッグするのに役立つログを表示する最も簡単な方法は、コンソールログを有効にすることです。
// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();
すべての資格情報は、SDK の他のクライアントと同じ方法で診断オプションを使用して構成できます。
注意： Azure Id ライブラリの要求と応答には、機密情報が含まれています。 アカウントのセキュリティを損なわないように、出力をカスタマイズするときにログを保護するには、予防措置を講じなければなりません。
DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions
{
Diagnostics =
{
LoggedHeaderNames = { "x-ms-request-id" },
LoggedQueryParameters = { "api-version" },
IsLoggingContentEnabled = true
}
};
認証の問題をトラブルシューティングする場合は、機密情報のログ記録を有効にすることもできます。 この種類のログ記録を有効にするには、 プロパティを IsLoggingContentEnabled に true設定します。 認証と承認の試行に使用されたアカウントの詳細のみをログに記録するには、 を に設定 IsAccountIdentifierLoggingEnabled します true。
DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions
{
Diagnostics =
{
LoggedHeaderNames = { "x-ms-request-id" },
LoggedQueryParameters = { "api-version" },
IsAccountIdentifierLoggingEnabled = true
}
};
スレッド セーフ
すべての資格情報インスタンス メソッドがスレッド セーフであり、相互に独立していることを保証します (ガイドライン)。 これにより、資格情報インスタンスを再利用するという推奨事項は、スレッド間でも常に安全になります。
その他の概念
クライアント オプション | 応答 | へのアクセス診断 | あざける | クライアントの有効期間
次の手順
Azure Identity での認証をサポートするクライアント ライブラリ
ここに記載されているクライアント ライブラリの多くは、 と Azure Identity ライブラリを使用TokenCredentialした認証をサポートしています。
また、追加のドキュメントやサンプルなど、その使用方法の詳細を確認できるリンクもあります。
の既知の問題
このライブラリでは、現在 、Azure AD B2C サービスに関連するシナリオはサポートされていません。
ライブラリのオープンな Azure.Identity 問題 については、こちらを参照してください。
共同作成
このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。
pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。
このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。
