Azure Identity Dotnet

1---
2name: azure-identity-dotnet
3description: |
4  Azure Identity SDK for .NET. Authentication library for Azure SDK clients using Microsoft Entra ID. Use for DefaultAzureCredential, managed identity, service principals, and developer credentials. Triggers: "Azure Identity", "DefaultAzureCredential", "ManagedIdentityCredential", "ClientSecretCredential", "authentication .NET", "Azure auth", "credential chain".
5package: Azure.Identity
6---
7 
8# Azure.Identity (.NET)
9 
10Authentication library for Azure SDK clients using Microsoft Entra ID (formerly Azure AD).
11 
12## Installation
13 
14```bash
15dotnet add package Azure.Identity
16 
17# For ASP.NET Core
18dotnet add package Microsoft.Extensions.Azure
19 
20# For brokered authentication (Windows)
21dotnet add package Azure.Identity.Broker
22```
23 
24**Current Versions**: Stable v1.17.1, Preview v1.18.0-beta.2
25 
26## Environment Variables
27 
28### Service Principal with Secret
29```bash
30AZURE_CLIENT_ID=<application-client-id>
31AZURE_TENANT_ID=<directory-tenant-id>
32AZURE_CLIENT_SECRET=<client-secret-value>
33```
34 
35### Service Principal with Certificate
36```bash
37AZURE_CLIENT_ID=<application-client-id>
38AZURE_TENANT_ID=<directory-tenant-id>
39AZURE_CLIENT_CERTIFICATE_PATH=<path-to-pfx-or-pem>
40AZURE_CLIENT_CERTIFICATE_PASSWORD=<certificate-password>  # Optional
41```
42 
43### Managed Identity
44```bash
45AZURE_CLIENT_ID=<user-assigned-managed-identity-client-id>  # Only for user-assigned
46```
47 
48## DefaultAzureCredential
49 
50The recommended credential for most scenarios. Tries multiple authentication methods in order:
51 
52| Order | Credential | Enabled by Default |
53|-------|------------|-------------------|
54| 1 | EnvironmentCredential | Yes |
55| 2 | WorkloadIdentityCredential | Yes |
56| 3 | ManagedIdentityCredential | Yes |
57| 4 | VisualStudioCredential | Yes |
58| 5 | VisualStudioCodeCredential | Yes |
59| 6 | AzureCliCredential | Yes |
60| 7 | AzurePowerShellCredential | Yes |
61| 8 | AzureDeveloperCliCredential | Yes |
62| 9 | InteractiveBrowserCredential | **No** |
63 
64### Basic Usage
65 
66```csharp
67using Azure.Identity;
68using Azure.Storage.Blobs;
69 
70var credential = new DefaultAzureCredential();
71var blobClient = new BlobServiceClient(
72    new Uri("https://myaccount.blob.core.windows.net"),
73    credential);
74```
75 
76### ASP.NET Core with Dependency Injection
77 
78```csharp
79using Azure.Identity;
80using Microsoft.Extensions.Azure;
81 
82builder.Services.AddAzureClients(clientBuilder =>
83{
84    clientBuilder.AddBlobServiceClient(
85        new Uri("https://myaccount.blob.core.windows.net"));
86    clientBuilder.AddSecretClient(
87        new Uri("https://myvault.vault.azure.net"));
88    
89    // Uses DefaultAzureCredential by default
90    clientBuilder.UseCredential(new DefaultAzureCredential());
91});
92```
93 
94### Customizing DefaultAzureCredential
95 
96```csharp
97var credential = new DefaultAzureCredential(
98    new DefaultAzureCredentialOptions
99    {
100        ExcludeEnvironmentCredential = true,
101        ExcludeManagedIdentityCredential = false,
102        ExcludeVisualStudioCredential = false,
103        ExcludeAzureCliCredential = false,
104        ExcludeInteractiveBrowserCredential = false, // Enable interactive
105        TenantId = "<tenant-id>",
106        ManagedIdentityClientId = "<user-assigned-mi-client-id>"
107    });
108```
109 
110## Credential Types
111 
112### ManagedIdentityCredential (Production)
113 
114```csharp
115// System-assigned managed identity
116var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);
117 
118// User-assigned by client ID
119var credential = new ManagedIdentityCredential(
120    ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
121 
122// User-assigned by resource ID
123var credential = new ManagedIdentityCredential(
124    ManagedIdentityId.FromUserAssignedResourceId("<resource-id>"));
125```
126 
127### ClientSecretCredential
128 
129```csharp
130var credential = new ClientSecretCredential(
131    tenantId: "<tenant-id>",
132    clientId: "<client-id>",
133    clientSecret: "<client-secret>");
134 
135var client = new SecretClient(
136    new Uri("https://myvault.vault.azure.net"),
137    credential);
138```
139 
140### ClientCertificateCredential
141 
142```csharp
143var certificate = X509CertificateLoader.LoadCertificateFromFile("MyCertificate.pfx");
144var credential = new ClientCertificateCredential(
145    tenantId: "<tenant-id>",
146    clientId: "<client-id>",
147    certificate);
148```
149 
150### ChainedTokenCredential (Custom Chain)
151 
152```csharp
153var credential = new ChainedTokenCredential(
154    new ManagedIdentityCredential(),
155    new AzureCliCredential());
156 
157var client = new SecretClient(
158    new Uri("https://myvault.vault.azure.net"),
159    credential);
160```
161 
162### Developer Credentials
163 
164```csharp
165// Azure CLI
166var credential = new AzureCliCredential();
167 
168// Azure PowerShell
169var credential = new AzurePowerShellCredential();
170 
171// Azure Developer CLI (azd)
172var credential = new AzureDeveloperCliCredential();
173 
174// Visual Studio
175var credential = new VisualStudioCredential();
176 
177// Interactive Browser
178var credential = new InteractiveBrowserCredential();
179```
180 
181## Environment-Based Configuration
182 
183```csharp
184// Production vs Development
185TokenCredential credential = builder.Environment.IsProduction()
186    ? new ManagedIdentityCredential("<client-id>")
187    : new DefaultAzureCredential();
188```
189 
190## Sovereign Clouds
191 
192```csharp
193var credential = new DefaultAzureCredential(
194    new DefaultAzureCredentialOptions
195    {
196        AuthorityHost = AzureAuthorityHosts.AzureGovernment
197    });
198 
199// Available authority hosts:
200// AzureAuthorityHosts.AzurePublicCloud (default)
201// AzureAuthorityHosts.AzureGovernment
202// AzureAuthorityHosts.AzureChina
203// AzureAuthorityHosts.AzureGermany
204```
205 
206## Credential Types Reference
207 
208| Category | Credential | Purpose |
209|----------|------------|---------|
210| **Chains** | `DefaultAzureCredential` | Preconfigured chain for dev-to-prod |
211| | `ChainedTokenCredential` | Custom credential chain |
212| **Azure-Hosted** | `ManagedIdentityCredential` | Azure managed identity |
213| | `WorkloadIdentityCredential` | Kubernetes workload identity |
214| | `EnvironmentCredential` | Environment variables |
215| **Service Principal** | `ClientSecretCredential` | Client ID + secret |
216| | `ClientCertificateCredential` | Client ID + certificate |
217| | `ClientAssertionCredential` | Signed client assertion |
218| **User** | `InteractiveBrowserCredential` | Browser-based auth |
219| | `DeviceCodeCredential` | Device code flow |
220| | `OnBehalfOfCredential` | Delegated identity |
221| **Developer** | `AzureCliCredential` | Azure CLI |
222| | `AzurePowerShellCredential` | Azure PowerShell |
223| | `AzureDeveloperCliCredential` | Azure Developer CLI |
224| | `VisualStudioCredential` | Visual Studio |
225 
226## Best Practices
227 
228### 1. Use Deterministic Credentials in Production
229 
230```csharp
231// Development
232var devCredential = new DefaultAzureCredential();
233 
234// Production - use specific credential
235var prodCredential = new ManagedIdentityCredential("<client-id>");
236```
237 
238### 2. Reuse Credential Instances
239 
240```csharp
241// Good: Single credential instance shared across clients
242var credential = new DefaultAzureCredential();
243var blobClient = new BlobServiceClient(blobUri, credential);
244var secretClient = new SecretClient(vaultUri, credential);
245```
246 
247### 3. Configure Retry Policies
248 
249```csharp
250var options = new ManagedIdentityCredentialOptions(
251    ManagedIdentityId.FromUserAssignedClientId(clientId))
252{
253    Retry =
254    {
255        MaxRetries = 3,
256        Delay = TimeSpan.FromSeconds(0.5),
257    }
258};
259var credential = new ManagedIdentityCredential(options);
260```
261 
262### 4. Enable Logging for Debugging
263 
264```csharp
265using Azure.Core.Diagnostics;
266 
267using AzureEventSourceListener listener = new((args, message) =>
268{
269    if (args is { EventSource.Name: "Azure-Identity" })
270    {
271        Console.WriteLine(message);
272    }
273}, EventLevel.LogAlways);
274```
275 
276## Error Handling
277 
278```csharp
279using Azure.Identity;
280using Azure.Security.KeyVault.Secrets;
281 
282var client = new SecretClient(
283    new Uri("https://myvault.vault.azure.net"),
284    new DefaultAzureCredential());
285 
286try
287{
288    KeyVaultSecret secret = await client.GetSecretAsync("secret1");
289}
290catch (AuthenticationFailedException e)
291{
292    Console.WriteLine($"Authentication Failed: {e.Message}");
293}
294catch (CredentialUnavailableException e)
295{
296    Console.WriteLine($"Credential Unavailable: {e.Message}");
297}
298```
299 
300## Key Exceptions
301 
302| Exception | Description |
303|-----------|-------------|
304| `AuthenticationFailedException` | Base exception for authentication errors |
305| `CredentialUnavailableException` | Credential cannot authenticate in current environment |
306| `AuthenticationRequiredException` | Interactive authentication is required |
307 
308## Managed Identity Support
309 
310Supported Azure services:
311- Azure App Service and Azure Functions
312- Azure Arc
313- Azure Cloud Shell
314- Azure Kubernetes Service (AKS)
315- Azure Service Fabric
316- Azure Virtual Machines
317- Azure Virtual Machine Scale Sets
318 
319## Thread Safety
320 
321All credential implementations are thread-safe. A single credential instance can be safely shared across multiple clients and threads.
322 
323## Related SDKs
324 
325| SDK | Purpose | Install |
326|-----|---------|---------|
327| `Azure.Identity` | Authentication (this SDK) | `dotnet add package Azure.Identity` |
328| `Microsoft.Extensions.Azure` | DI integration | `dotnet add package Microsoft.Extensions.Azure` |
329| `Azure.Identity.Broker` | Brokered auth (Windows) | `dotnet add package Azure.Identity.Broker` |
330 
331## Reference Links
332 
333| Resource | URL |
334|----------|-----|
335| NuGet Package | https://www.nuget.org/packages/Azure.Identity |
336| API Reference | https://learn.microsoft.com/dotnet/api/azure.identity |
337| Credential Chains | https://learn.microsoft.com/dotnet/azure/sdk/authentication/credential-chains |
338| Best Practices | https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices |
339| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity |
340