適用於 .NET 的 Azure Identity 程式庫
使用 Microsoft Entra ID 為 Azure SDK 用戶端提供驗證功能的程式庫。
安裝
dotnet add package Azure.Identity
# 適用於 ASP.NET Core 整合
dotnet add package Microsoft.Extensions.Azure
# 適用於代理驗證和 Visual Studio Code 認證支援
dotnet add package Azure.Identity.Broker
環境變數
服務主體搭配祕密
AZURE_CLIENT_ID=<應用程式-用戶端-識別碼>
AZURE_TENANT_ID=<目錄-租用戶-識別碼>
AZURE_CLIENT_SECRET=<用戶端-祕密-值>
服務主體搭配憑證
AZURE_CLIENT_ID=<應用程式-用戶端-識別碼>
AZURE_TENANT_ID=<目錄-租用戶-識別碼>
AZURE_CLIENT_CERTIFICATE_PATH=<pfx-或-pem-檔案路徑>
AZURE_CLIENT_CERTIFICATE_PASSWORD=<憑證密碼> # 選填
受控識別
AZURE_CLIENT_ID=<使用者指派受控識別的用戶端識別碼> # 僅適用於使用者指派
DefaultAzureCredential
大多數情況下的建議認證。依序嘗試多種驗證方法。請參閱 DefaultAzureCredential 概觀 了解目前的認證鏈結順序和預設值。
基本用法
using Azure.Identity;
using Azure.Storage.Blobs;
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(
new Uri("https://myaccount.blob.core.windows.net"),
credential);
ASP.NET Core 搭配相依性注入
using Azure.Identity;
using Microsoft.Extensions.Azure;
builder.Services.AddAzureClients(clientBuilder =>
{
clientBuilder.AddBlobServiceClient(
new Uri("https://myaccount.blob.core.windows.net"));
clientBuilder.AddSecretClient(
new Uri("https://myvault.vault.azure.net"));
// 預設使用 DefaultAzureCredential
clientBuilder.UseCredential(new DefaultAzureCredential());
});
自訂 DefaultAzureCredential
var credential = new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
ExcludeEnvironmentCredential = true,
ExcludeManagedIdentityCredential = false,
ExcludeVisualStudioCredential = false,
ExcludeAzureCliCredential = false,
ExcludeInteractiveBrowserCredential = false, // 啟用互動式
TenantId = "<租用戶-識別碼>",
ManagedIdentityClientId = "<使用者指派受控識別的用戶端識別碼>"
});
認證類型
ManagedIdentityCredential (生產環境)
// 系統指派受控識別
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);
// 依用戶端識別碼的使用者指派
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedClientId("<用戶端-識別碼>"));
// 依資源識別碼的使用者指派
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedResourceId("<資源-識別碼>"));
// 依物件識別碼的使用者指派
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedObjectId("<物件-識別碼>"));
ClientSecretCredential
var credential = new ClientSecretCredential(
tenantId: "<租用戶-識別碼>",
clientId: "<用戶端-識別碼>",
clientSecret: "<用戶端-祕密>");
var client = new SecretClient(
new Uri("https://myvault.vault.azure.net"),
credential);
ClientCertificateCredential
var certificate = X509CertificateLoader.LoadCertificateFromFile("MyCertificate.pfx");
var credential = new ClientCertificateCredential(
tenantId: "<租用戶-識別碼>",
clientId: "<用戶端-識別碼>",
certificate);
ChainedTokenCredential (自訂鏈結)
var credential = new ChainedTokenCredential(
new ManagedIdentityCredential(),
new AzureCliCredential());
var client = new SecretClient(
new Uri("https://myvault.vault.azure.net"),
credential);
開發人員認證
// Azure CLI
var credential = new AzureCliCredential();
// Azure PowerShell
var credential = new AzurePowerShellCredential();
// Azure Developer CLI (azd)
var credential = new AzureDeveloperCliCredential();
// Visual Studio
var credential = new VisualStudioCredential();
// 互動式瀏覽器
var credential = new InteractiveBrowserCredential();
基於環境的設定
// 生產環境與開發環境
TokenCredential credential = builder.Environment.IsProduction()
? new ManagedIdentityCredential("<用戶端-識別碼>")
: new DefaultAzureCredential();
主權雲端
var credential = new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
AuthorityHost = AzureAuthorityHosts.AzureGovernment
});
// 可用的授權主機：
// AzureAuthorityHosts.AzurePublicCloud (預設)
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina
認證類型參考
| 類別 | 認證 | 用途 |
|---|---|---|
| 鏈結 | DefaultAzureCredential | 從開發到生產的預設鏈結 |
ChainedTokenCredential | 自訂認證鏈結 | |
| Azure 託管 | ManagedIdentityCredential | Azure 受控識別 |
WorkloadIdentityCredential | Kubernetes 工作負載身分識別 | |
EnvironmentCredential | 環境變數 | |
| 服務主體 | ClientSecretCredential | 用戶端識別碼 + 祕密 |
ClientCertificateCredential | 用戶端識別碼 + 憑證 | |
ClientAssertionCredential | 已簽署用戶端判斷提示 | |
| 使用者 | InteractiveBrowserCredential | 瀏覽器為基礎的驗證 |
DeviceCodeCredential | 裝置代碼流程 | |
OnBehalfOfCredential | 委派身分識別 | |
| 開發人員 | AzureCliCredential | Azure CLI |
AzurePowerShellCredential | Azure PowerShell | |
AzureDeveloperCliCredential | Azure Developer CLI | |
VisualStudioCredential | Visual Studio |
最佳實務
1. 在生產環境中使用確定性認證
// 開發環境
var devCredential = new DefaultAzureCredential();
// 生產環境 - 使用特定認證
var prodCredential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedClientId("<用戶端-識別碼>"));
2. 重複使用認證執行個體
// 良好：單一認證執行個體在多個用戶端之間共用
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(blobUri, credential);
var secretClient = new SecretClient(vaultUri, credential);
3. 設定重試原則
var options = new ManagedIdentityCredentialOptions(
ManagedIdentityId.FromUserAssignedClientId(clientId))
{
Retry =
{
MaxRetries = 3,
Delay = TimeSpan.FromSeconds(0.5),
}
};
var credential = new ManagedIdentityCredential(options);
4. 啟用記錄功能以進行偵錯
using Azure.Core.Diagnostics;
using AzureEventSourceListener listener = new((args, message) =>
{
if (args is { EventSource.Name: "Azure-Identity" })
{
Console.WriteLine(message);
}
}, EventLevel.LogAlways);
錯誤處理
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
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($"驗證失敗：{e.Message}");
}
catch (CredentialUnavailableException e)
{
Console.WriteLine($"認證無法使用：{e.Message}");
}
主要例外狀況
| 例外狀況 | 說明 |
|---|---|
AuthenticationFailedException | 驗證錯誤的基底例外狀況 |
CredentialUnavailableException | 在目前環境中無法進行驗證的認證 |
AuthenticationRequiredException | 需要互動式驗證 |
受控識別支援
支援的 Azure 服務：
- Azure App Service 和 Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service (AKS)
- Azure Service Fabric
- Azure 虛擬機器
- Azure 虛擬機器擴展集
執行緒安全性
所有認證實作都是執行緒安全的。單一認證執行個體可以安全地在多個用戶端和執行緒之間共用。
相關套件
| 套件 | 用途 | 安裝方式 |
|---|---|---|
Azure.Identity | 驗證（此程式庫） | dotnet add package Azure.Identity |
Microsoft.Extensions.Azure | DI 整合 | dotnet add package Microsoft.Extensions.Azure |
Azure.Identity.Broker | 代理驗證 | dotnet add package Azure.Identity.Broker |