Azure.Identity (.NET)
Authentication library for Azure SDK clients using Microsoft Entra ID (formerly Azure AD).
Installation
dotnet add package Azure.Identity
For ASP.NET Core
dotnet add package Microsoft.Extensions.Azure
For brokered authentication (Windows)
dotnet add package Azure.Identity.Broker
Current Versions: Stable v1.17.1, Preview v1.18.0-beta.2
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:
Order Credential Enabled by Default
1 EnvironmentCredential Yes
2 WorkloadIdentityCredential Yes
3 ManagedIdentityCredential Yes
4 VisualStudioCredential Yes
5 VisualStudioCodeCredential Yes
6 AzureCliCredential Yes
7 AzurePowerShellCredential Yes
8 AzureDeveloperCliCredential Yes
9 InteractiveBrowserCredential No
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>"));
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 // AzureAuthorityHosts.AzureGermany
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
- Use Deterministic Credentials in Production
// Development var devCredential = new DefaultAzureCredential();
// Production - use specific credential var prodCredential = new ManagedIdentityCredential("<client-id>");
- 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);
- Configure Retry Policies
var options = new ManagedIdentityCredentialOptions( ManagedIdentityId.FromUserAssignedClientId(clientId)) { Retry = { MaxRetries = 3, Delay = TimeSpan.FromSeconds(0.5), } }; var credential = new ManagedIdentityCredential(options);
- 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 SDKs
SDK Purpose Install
Azure.Identity
Authentication (this SDK) dotnet add package Azure.Identity
Microsoft.Extensions.Azure
DI integration dotnet add package Microsoft.Extensions.Azure
Azure.Identity.Broker
Brokered auth (Windows) dotnet add package Azure.Identity.Broker
Reference Links
Resource URL
NuGet Package https://www.nuget.org/packages/Azure.Identity
API Reference https://learn.microsoft.com/dotnet/api/azure.identity
Credential Chains https://learn.microsoft.com/dotnet/azure/sdk/authentication/credential-chains
Best Practices https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices
GitHub Source https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity