Azure Identity library for .NET
Authentication library for Azure SDK clients using Microsoft Entra ID.
Installation
dotnet add package Azure.Identity
# For ASP.NET Core integration
dotnet add package Microsoft.Extensions.Azure
# For brokered authentication and Visual Studio Code credential support
dotnet add package Azure.Identity.Broker
Environment Variables
Service Principal with Secret
AZURE_CLIENT_ID=<application-client-id>
AZURE_TENANT_ID=<directory-tenant-id>
AZURE_CLIENT_SECRET=<client-secret-value>
Service Principal with Certificate
AZURE_CLIENT_ID=<application-client-id>
AZURE_TENANT_ID=<directory-tenant-id>
AZURE_CLIENT_CERTIFICATE_PATH=<path-to-pfx-or-pem>
AZURE_CLIENT_CERTIFICATE_PASSWORD=<certificate-password> # Optional
Managed Identity
AZURE_CLIENT_ID=<user-assigned-managed-identity-client-id> # Only for user-assigned
DefaultAzureCredential
The recommended credential for most scenarios. Tries multiple authentication methods in order. See DefaultAzureCredential overview for the current credential chain order and defaults.
Basic Usage
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 with Dependency Injection
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"));
// Uses DefaultAzureCredential by default
clientBuilder.UseCredential(new DefaultAzureCredential());
});
Customizing DefaultAzureCredential
var credential = new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
ExcludeEnvironmentCredential = true,
ExcludeManagedIdentityCredential = false,
ExcludeVisualStudioCredential = false,
ExcludeAzureCliCredential = false,
ExcludeInteractiveBrowserCredential = false, // Enable interactive
TenantId = "<tenant-id>",
ManagedIdentityClientId = "<user-assigned-mi-client-id>"
});
Credential Types
ManagedIdentityCredential (Production)
// System-assigned managed identity
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);
// User-assigned by client ID
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
// User-assigned by resource ID
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedResourceId("<resource-id>"));
// User-assigned by object ID
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedObjectId("<object-id>"));
ClientSecretCredential
var credential = new ClientSecretCredential(
tenantId: "<tenant-id>",
clientId: "<client-id>",
clientSecret: "<client-secret>");
var client = new SecretClient(
new Uri("https://myvault.vault.azure.net"),
credential);
ClientCertificateCredential
var certificate = X509CertificateLoader.LoadCertificateFromFile("MyCertificate.pfx");
var credential = new ClientCertificateCredential(
tenantId: "<tenant-id>",
clientId: "<client-id>",
certificate);
ChainedTokenCredential (Custom Chain)
var credential = new ChainedTokenCredential(
new ManagedIdentityCredential(),
new AzureCliCredential());
var client = new SecretClient(
new Uri("https://myvault.vault.azure.net"),
credential);
Developer Credentials
// 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();
// Interactive Browser
var credential = new InteractiveBrowserCredential();
Environment-Based Configuration
// Production vs Development
TokenCredential credential = builder.Environment.IsProduction()
? new ManagedIdentityCredential("<client-id>")
: new DefaultAzureCredential();
Sovereign Clouds
var credential = new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
AuthorityHost = AzureAuthorityHosts.AzureGovernment
});
// Available authority hosts:
// AzureAuthorityHosts.AzurePublicCloud (default)
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina
Credential Types Reference
| Category | Credential | Purpose |
|---|
| Chains | DefaultAzureCredential | Preconfigured chain for dev-to-prod |
| ChainedTokenCredential | Custom credential chain |
| Azure-Hosted | ManagedIdentityCredential | Azure managed identity |
| WorkloadIdentityCredential | Kubernetes workload identity |
| EnvironmentCredential | Environment variables |
| Service Principal | ClientSecretCredential | Client ID + secret |
| ClientCertificateCredential | Client ID + certificate |
| ClientAssertionCredential | Signed client assertion |
| User | InteractiveBrowserCredential | Browser-based auth |
| DeviceCodeCredential | Device code flow |
| OnBehalfOfCredential | Delegated identity |
| Developer | AzureCliCredential | Azure CLI |
| AzurePowerShellCredential | Azure PowerShell |
| AzureDeveloperCliCredential | Azure Developer CLI |
| VisualStudioCredential | Visual Studio |
Best Practices
1. Use Deterministic Credentials in Production
// Development
var devCredential = new DefaultAzureCredential();
// Production - use specific credential
var prodCredential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
2. Reuse Credential Instances
// Good: Single credential instance shared across clients
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(blobUri, credential);
var secretClient = new SecretClient(vaultUri, credential);
3. Configure Retry Policies
var options = new ManagedIdentityCredentialOptions(
ManagedIdentityId.FromUserAssignedClientId(clientId))
{
Retry =
{
MaxRetries = 3,
Delay = TimeSpan.FromSeconds(0.5),
}
};
var credential = new ManagedIdentityCredential(options);
4. Enable Logging for Debugging
using Azure.Core.Diagnostics;
using AzureEventSourceListener listener = new((args, message) =>
{
if (args is { EventSource.Name: "Azure-Identity" })
{
Console.WriteLine(message);
}
}, EventLevel.LogAlways);
Error Handling
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($"Authentication Failed: {e.Message}");
}
catch (CredentialUnavailableException e)
{
Console.WriteLine($"Credential Unavailable: {e.Message}");
}
Key Exceptions
| Exception | Description |
|---|
AuthenticationFailedException | Base exception for authentication errors |
CredentialUnavailableException | Credential cannot authenticate in current environment |
AuthenticationRequiredException | Interactive authentication is required |
Managed Identity Support
Supported Azure services:
- Azure App Service and Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service (AKS)
- Azure Service Fabric
- Azure Virtual Machines
- Azure Virtual Machine Scale Sets
Thread Safety
All credential implementations are thread-safe. A single credential instance can be safely shared across multiple clients and threads.
Related packages
| Package | Purpose | Install |
|---|
Azure.Identity | Authentication (this library) | dotnet add package Azure.Identity |
Microsoft.Extensions.Azure | DI integration | dotnet add package Microsoft.Extensions.Azure |
Azure.Identity.Broker | Brokered auth | dotnet add package Azure.Identity.Broker |
Reference Links