0
# Azure Identity
1

2
The Azure Identity library provides Microsoft Entra ID (formerly Azure Active Directory) token authentication support across the Azure SDK. It offers a comprehensive set of TokenCredential implementations that can authenticate with Azure services using various authentication flows including managed identity, service principals, developer tools, and interactive authentication methods.
3

4
## Package Information
5

6
- **Package Name**: azure-identity
7
- **Package Type**: maven
8
- **Group ID**: com.azure
9
- **Artifact ID**: azure-identity
10
- **Language**: Java
11
- **Installation**: Add to Maven dependencies with group `com.azure` and artifact `azure-identity`
12

13
## Core Imports
14

15
```java
16
import com.azure.identity.*;
17
import com.azure.core.credential.TokenCredential;
18
```
19

20
For specific credential types:
21

22
```java
23
import com.azure.identity.DefaultAzureCredential;
24
import com.azure.identity.DefaultAzureCredentialBuilder;
25
import com.azure.identity.ManagedIdentityCredential;
26
import com.azure.identity.ManagedIdentityCredentialBuilder;
27
import com.azure.identity.ClientSecretCredential;
28
import com.azure.identity.ClientSecretCredentialBuilder;
29
```
30

31
## Basic Usage
32

33
```java
34
import com.azure.identity.DefaultAzureCredential;
35
import com.azure.identity.DefaultAzureCredentialBuilder;
36

37
// Create default credential chain for most common scenarios
38
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
39

40
// Use with any Azure SDK client
41
SecretClient client = new SecretClientBuilder()
42
    .vaultUrl("https://myvault.vault.azure.net/")
43
    .credential(credential)
44
    .buildClient();
45
```
46

47
## Architecture
48

49
The Azure Identity library is built around several key concepts:
50

51
- **TokenCredential Interface**: All credentials implement this interface from azure-core
52
- **Credential Builders**: Fluent builder pattern for configuring credentials
53
- **Authentication Flows**: Support for various OAuth2 and Azure-specific flows
54
- **Token Caching**: Automatic token caching and refresh capabilities
55
- **Multi-tenant Support**: Ability to authenticate across multiple Azure tenants
56

57
## Capabilities
58

59
### Default Authentication Chain
60

61
The recommended approach for most applications, trying multiple authentication methods in sequence.
62

63
```java { .api }
64
class DefaultAzureCredential extends ChainedTokenCredential implements TokenCredential {
65
    // Built using DefaultAzureCredentialBuilder
66
}
67

68
class DefaultAzureCredentialBuilder extends CredentialBuilderBase<DefaultAzureCredentialBuilder> {
69
    DefaultAzureCredentialBuilder tenantId(String tenantId);
70
    DefaultAzureCredentialBuilder authorityHost(String authorityHost);
71
    DefaultAzureCredentialBuilder managedIdentityClientId(String clientId);
72
    DefaultAzureCredentialBuilder workloadIdentityClientId(String clientId);
73
    DefaultAzureCredentialBuilder managedIdentityResourceId(String resourceId);
74
    DefaultAzureCredentialBuilder executorService(ExecutorService executorService);
75
    DefaultAzureCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
76
    DefaultAzureCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
77
    DefaultAzureCredentialBuilder credentialProcessTimeout(Duration credentialProcessTimeout);
78
    DefaultAzureCredentialBuilder disableInstanceDiscovery();
79
    DefaultAzureCredential build();
80
}
81
```
82

83
[Default Azure Credential](./default-azure-credential.md)
84

85
### Managed Identity Authentication
86

87
Authenticate using Azure Managed Identity for Azure-hosted applications.
88

89
```java { .api }
90
class ManagedIdentityCredential implements TokenCredential {
91
    String getClientId();
92
    Mono<AccessToken> getToken(TokenRequestContext request);
93
}
94

95
class ManagedIdentityCredentialBuilder extends CredentialBuilderBase<ManagedIdentityCredentialBuilder> {
96
    ManagedIdentityCredentialBuilder clientId(String clientId);
97
    ManagedIdentityCredentialBuilder resourceId(String resourceId);
98
    ManagedIdentityCredentialBuilder objectId(String objectId);
99
    ManagedIdentityCredentialBuilder executorService(ExecutorService executorService);
100
    ManagedIdentityCredential build();
101
}
102
```
103

104
[Managed Identity Credential](./managed-identity-credential.md)
105

106
### Service Principal Authentication
107

108
Authenticate using service principal credentials with client secrets or certificates.
109

110
```java { .api }
111
class ClientSecretCredential implements TokenCredential {
112
    Mono<AccessToken> getToken(TokenRequestContext request);
113
    AccessToken getTokenSync(TokenRequestContext request);
114
}
115

116
class ClientSecretCredentialBuilder extends AadCredentialBuilderBase<ClientSecretCredentialBuilder> {
117
    ClientSecretCredentialBuilder clientSecret(String clientSecret);
118
    ClientSecretCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
119
    ClientSecretCredential build();
120
}
121

122
class ClientCertificateCredential implements TokenCredential {
123
    Mono<AccessToken> getToken(TokenRequestContext request);
124
    AccessToken getTokenSync(TokenRequestContext request);
125
}
126

127
class ClientCertificateCredentialBuilder extends AadCredentialBuilderBase<ClientCertificateCredentialBuilder> {
128
    ClientCertificateCredentialBuilder pemCertificate(String certificatePath);
129
    ClientCertificateCredentialBuilder pemCertificate(InputStream certificate);
130
    ClientCertificateCredentialBuilder pfxCertificate(String certificatePath);
131
    ClientCertificateCredentialBuilder pfxCertificate(InputStream certificate);
132
    ClientCertificateCredentialBuilder clientCertificatePassword(String clientCertificatePassword);
133
    ClientCertificateCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
134
    ClientCertificateCredentialBuilder sendCertificateChain(boolean sendCertificateChain);
135
    ClientCertificateCredential build();
136
}
137
```
138

139
[Service Principal Authentication](./service-principal-authentication.md)
140

141
### Interactive User Authentication
142

143
Authenticate users through interactive flows including browser-based and device code authentication.
144

145
```java { .api }
146
class InteractiveBrowserCredential implements TokenCredential {
147
    Mono<AccessToken> getToken(TokenRequestContext request);
148
    AccessToken getTokenSync(TokenRequestContext request);
149
    Mono<AuthenticationRecord> authenticate(TokenRequestContext request);
150
    Mono<AuthenticationRecord> authenticate();
151
}
152

153
class InteractiveBrowserCredentialBuilder extends AadCredentialBuilderBase<InteractiveBrowserCredentialBuilder> {
154
    InteractiveBrowserCredentialBuilder authenticationRecord(AuthenticationRecord authenticationRecord);
155
    InteractiveBrowserCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
156
    InteractiveBrowserCredentialBuilder redirectUrl(String redirectUrl);
157
    InteractiveBrowserCredentialBuilder disableAutomaticAuthentication();
158
    InteractiveBrowserCredentialBuilder loginHint(String loginHint);
159
    InteractiveBrowserCredentialBuilder browserCustomizationOptions(BrowserCustomizationOptions browserCustomizationOptions);
160
    InteractiveBrowserCredential build();
161
}
162

163
class DeviceCodeCredential implements TokenCredential {
164
    Mono<AccessToken> getToken(TokenRequestContext request);
165
    AccessToken getTokenSync(TokenRequestContext request);
166
    Mono<AuthenticationRecord> authenticate(TokenRequestContext request);
167
    Mono<AuthenticationRecord> authenticate();
168
}
169

170
class DeviceCodeCredentialBuilder extends AadCredentialBuilderBase<DeviceCodeCredentialBuilder> {
171
    DeviceCodeCredentialBuilder challengeConsumer(Consumer<DeviceCodeInfo> challengeConsumer);
172
    DeviceCodeCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
173
    DeviceCodeCredentialBuilder authenticationRecord(AuthenticationRecord authenticationRecord);
174
    DeviceCodeCredentialBuilder disableAutomaticAuthentication();
175
    DeviceCodeCredential build();
176
}
177
```
178

179
[Interactive User Authentication](./interactive-user-authentication.md)
180

181
### Developer Tool Credentials
182

183
Authenticate using cached credentials from Azure development tools.
184

185
```java { .api }
186
class AzureCliCredential implements TokenCredential {
187
    Mono<AccessToken> getToken(TokenRequestContext request);
188
    AccessToken getTokenSync(TokenRequestContext request);
189
}
190

191
class AzureCliCredentialBuilder extends CredentialBuilderBase<AzureCliCredentialBuilder> {
192
    AzureCliCredentialBuilder tenantId(String tenantId);
193
    AzureCliCredentialBuilder processTimeout(Duration processTimeout);
194
    AzureCliCredentialBuilder subscription(String subscription);
195
    AzureCliCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
196
    AzureCliCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
197
    AzureCliCredential build();
198
}
199

200
class AzurePowerShellCredential implements TokenCredential {
201
    Mono<AccessToken> getToken(TokenRequestContext request);
202
}
203

204
class AzurePowerShellCredentialBuilder extends CredentialBuilderBase<AzurePowerShellCredentialBuilder> {
205
    AzurePowerShellCredentialBuilder tenantId(String tenantId);
206
    AzurePowerShellCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
207
    AzurePowerShellCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
208
    AzurePowerShellCredential build();
209
}
210
```
211

212
[Developer Tool Credentials](./developer-tool-credentials.md)
213

214
### Advanced Authentication Flows
215

216
Support for specialized authentication scenarios including on-behalf-of flow and workload identity.
217

218
```java { .api }
219
class OnBehalfOfCredential implements TokenCredential {
220
    Mono<AccessToken> getToken(TokenRequestContext request);
221
    AccessToken getTokenSync(TokenRequestContext request);
222
}
223

224
class OnBehalfOfCredentialBuilder extends AadCredentialBuilderBase<OnBehalfOfCredentialBuilder> {
225
    OnBehalfOfCredentialBuilder clientSecret(String clientSecret);
226
    OnBehalfOfCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
227
    OnBehalfOfCredentialBuilder pemCertificate(String pemCertificatePath);
228
    OnBehalfOfCredentialBuilder pfxCertificate(String pfxCertificatePath);
229
    OnBehalfOfCredentialBuilder clientCertificatePassword(String clientCertificatePassword);
230
    OnBehalfOfCredentialBuilder sendCertificateChain(boolean sendCertificateChain);
231
    OnBehalfOfCredentialBuilder userAssertion(String userAssertion);
232
    OnBehalfOfCredentialBuilder clientAssertion(Supplier<String> clientAssertionSupplier);
233
    OnBehalfOfCredential build();
234
}
235

236
class WorkloadIdentityCredential implements TokenCredential {
237
    Mono<AccessToken> getToken(TokenRequestContext request);
238
    AccessToken getTokenSync(TokenRequestContext request);
239
}
240

241
class WorkloadIdentityCredentialBuilder extends AadCredentialBuilderBase<WorkloadIdentityCredentialBuilder> {
242
    WorkloadIdentityCredentialBuilder tokenFilePath(String tokenFilePath);
243
    WorkloadIdentityCredential build();
244
}
245
```
246

247
[Advanced Authentication Flows](./advanced-authentication-flows.md)
248

249
### Credential Chaining and Customization
250

251
Chain multiple credentials together and customize authentication behavior.
252

253
```java { .api }
254
class ChainedTokenCredential implements TokenCredential {
255
    Mono<AccessToken> getToken(TokenRequestContext request);
256
    AccessToken getTokenSync(TokenRequestContext request);
257
}
258

259
class ChainedTokenCredentialBuilder {
260
    ChainedTokenCredentialBuilder addLast(TokenCredential credential);
261
    ChainedTokenCredential build();
262
}
263
```
264

265
[Credential Chaining](./credential-chaining.md)
266

267
### Environment Variable Authentication
268

269
Authenticate using environment variables for service principal credentials. Supports both client secret and client certificate authentication.
270

271
```java { .api }
272
class EnvironmentCredential implements TokenCredential {
273
    Mono<AccessToken> getToken(TokenRequestContext request);
274
    AccessToken getTokenSync(TokenRequestContext request);
275
}
276

277
class EnvironmentCredentialBuilder extends CredentialBuilderBase<EnvironmentCredentialBuilder> {
278
    EnvironmentCredentialBuilder authorityHost(String authorityHost);
279
    EnvironmentCredentialBuilder executorService(ExecutorService executorService);
280
    EnvironmentCredential build();
281
}
282
```
283

284
[Environment Credential](./environment-credential.md)
285

286
### Username Password Authentication
287

288
Authenticate using username and password credentials. **Deprecated** due to lack of multifactor authentication support.
289

290
```java { .api }
291
@Deprecated
292
class UsernamePasswordCredential implements TokenCredential {
293
    Mono<AccessToken> getToken(TokenRequestContext request);
294
    AccessToken getTokenSync(TokenRequestContext request);
295
    Mono<AuthenticationRecord> authenticate(TokenRequestContext request);
296
    Mono<AuthenticationRecord> authenticate();
297
}
298

299
@Deprecated
300
class UsernamePasswordCredentialBuilder extends AadCredentialBuilderBase<UsernamePasswordCredentialBuilder> {
301
    UsernamePasswordCredentialBuilder username(String username);
302
    UsernamePasswordCredentialBuilder password(String password);
303
    UsernamePasswordCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
304
    UsernamePasswordCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
305
    UsernamePasswordCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
306
    UsernamePasswordCredential build();
307
}
308
```
309

310
[Username Password Authentication](./username-password-authentication.md)
311

312
### Client Assertion Authentication
313

314
Authenticate using client assertions (JWT bearer tokens) for service principal authentication.
315

316
```java { .api }
317
class ClientAssertionCredential implements TokenCredential {
318
    Mono<AccessToken> getToken(TokenRequestContext request);
319
    AccessToken getTokenSync(TokenRequestContext request);
320
}
321

322
class ClientAssertionCredentialBuilder extends AadCredentialBuilderBase<ClientAssertionCredentialBuilder> {
323
    ClientAssertionCredentialBuilder clientAssertion(Supplier<String> clientAssertionSupplier);
324
    ClientAssertionCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
325
    ClientAssertionCredential build();
326
}
327
```
328

329
[Client Assertion Authentication](./client-assertion-authentication.md)
330

331
### Authorization Code Authentication
332

333
Authenticate using OAuth 2.0 authorization code flow for web applications.
334

335
```java { .api }
336
class AuthorizationCodeCredential implements TokenCredential {
337
    Mono<AccessToken> getToken(TokenRequestContext request);
338
}
339

340
class AuthorizationCodeCredentialBuilder extends AadCredentialBuilderBase<AuthorizationCodeCredentialBuilder> {
341
    AuthorizationCodeCredentialBuilder authorizationCode(String authCode);
342
    AuthorizationCodeCredentialBuilder redirectUrl(String redirectUrl);
343
    AuthorizationCodeCredentialBuilder clientSecret(String clientSecret);
344
    AuthorizationCodeCredential build();
345
}
346
```
347

348
[Authorization Code Authentication](./authorization-code-authentication.md)
349

350
### Azure Developer CLI Authentication
351

352
Authenticate using Azure Developer CLI (azd) cached credentials from development environments.
353

354
```java { .api }
355
class AzureDeveloperCliCredential implements TokenCredential {
356
    Mono<AccessToken> getToken(TokenRequestContext request);
357
    AccessToken getTokenSync(TokenRequestContext request);
358
}
359

360
class AzureDeveloperCliCredentialBuilder extends CredentialBuilderBase<AzureDeveloperCliCredentialBuilder> {
361
    AzureDeveloperCliCredentialBuilder tenantId(String tenantId);
362
    AzureDeveloperCliCredentialBuilder processTimeout(Duration processTimeout);
363
    AzureDeveloperCliCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
364
    AzureDeveloperCliCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
365
    AzureDeveloperCliCredential build();
366
}
367
```
368

369
[Azure Developer CLI Authentication](./azure-developer-cli-authentication.md)
370

371
### Azure Pipelines Authentication
372

373
Authenticate using Azure Pipelines service connections for CI/CD scenarios.
374

375
```java { .api }
376
class AzurePipelinesCredential implements TokenCredential {
377
    Mono<AccessToken> getToken(TokenRequestContext request);
378
    AccessToken getTokenSync(TokenRequestContext request);
379
}
380

381
class AzurePipelinesCredentialBuilder extends AadCredentialBuilderBase<AzurePipelinesCredentialBuilder> {
382
    AzurePipelinesCredentialBuilder serviceConnectionId(String serviceConnectionId);
383
    AzurePipelinesCredentialBuilder systemAccessToken(String systemAccessToken);
384
    AzurePipelinesCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
385
    AzurePipelinesCredential build();
386
}
387
```
388

389
[Azure Pipelines Authentication](./azure-pipelines-authentication.md)
390

391
### Shared Token Cache Authentication
392

393
Legacy mechanism for authenticating using MSAL shared token cache (formerly Visual Studio integration).
394

395
```java { .api }
396
class SharedTokenCacheCredential implements TokenCredential {
397
    Mono<AccessToken> getToken(TokenRequestContext request);
398
}
399

400
class SharedTokenCacheCredentialBuilder extends AadCredentialBuilderBase<SharedTokenCacheCredentialBuilder> {
401
    SharedTokenCacheCredentialBuilder username(String username);
402
    SharedTokenCacheCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
403
    SharedTokenCacheCredentialBuilder authenticationRecord(AuthenticationRecord authenticationRecord);
404
    SharedTokenCacheCredential build();
405
}
406
```
407

408
[Shared Token Cache Authentication](./shared-token-cache-authentication.md)
409

410
### Visual Studio Code Authentication
411

412
**Deprecated** authentication using Visual Studio Code Azure Account extension credentials.
413

414
```java { .api }
415
@Deprecated
416
class VisualStudioCodeCredential implements TokenCredential {
417
    Mono<AccessToken> getToken(TokenRequestContext request);
418
}
419

420
@Deprecated
421
class VisualStudioCodeCredentialBuilder extends CredentialBuilderBase<VisualStudioCodeCredentialBuilder> {
422
    VisualStudioCodeCredentialBuilder tenantId(String tenantId);
423
    VisualStudioCodeCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
424
    VisualStudioCodeCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
425
    VisualStudioCodeCredential build();
426
}
427
```
428

429
[Visual Studio Code Authentication](./visual-studio-code-authentication.md)
430

431
### Configuration and Utilities
432

433
Configuration classes and utility functions for customizing authentication behavior.
434

435
```java { .api }
436
class AzureAuthorityHosts {
437
    static final String AZURE_PUBLIC_CLOUD = "https://login.microsoftonline.com/";
438
    static final String AZURE_CHINA = "https://login.chinacloudapi.cn/";
439
    static final String AZURE_GOVERNMENT = "https://login.microsoftonline.us/";
440
}
441

442
class AuthenticationRecord {
443
    String getAuthority();
444
    String getHomeAccountId();
445
    String getTenantId();
446
    String getClientId();
447
    String getUsername();
448
    void serialize(OutputStream outputStream);
449
    static AuthenticationRecord deserialize(InputStream inputStream);
450
}
451

452
class DeviceCodeInfo {
453
    DeviceCodeInfo(String userCode, String deviceCode, String verificationUrl, OffsetDateTime expiresOn, String message);
454
    String getUserCode();
455
    String getDeviceCode();
456
    String getVerificationUrl();
457
    OffsetDateTime getExpiresOn();
458
    String getMessage();
459
}
460

461
class BrowserCustomizationOptions {
462
    BrowserCustomizationOptions();
463
    BrowserCustomizationOptions setSuccessMessage(String successMessage);
464
    BrowserCustomizationOptions setErrorMessage(String errorMessage);
465
    String getSuccessMessage();
466
    String getErrorMessage();
467
}
468

469
class TokenCachePersistenceOptions {
470
    TokenCachePersistenceOptions();
471
    TokenCachePersistenceOptions setUnencryptedStorageAllowed(boolean unencryptedStorageAllowed);
472
    boolean isUnencryptedStorageAllowed();
473
    TokenCachePersistenceOptions setName(String name);
474
    String getName();
475
}
476

477
class AuthenticationUtil {
478
    static Supplier<String> getBearerTokenSupplier(TokenCredential credential, String... scopes);
479
}
480

481
abstract class CredentialBuilderBase<T extends CredentialBuilderBase<T>> {
482
    T maxRetry(int maxRetry);
483
    T retryTimeout(Function<Duration, Duration> retryTimeout);
484
    T httpClient(HttpClient client);
485
    T configuration(Configuration configuration);
486
    T clientOptions(ClientOptions clientOptions);
487
    T httpLogOptions(HttpLogOptions logOptions);
488
    T retryPolicy(RetryPolicy retryPolicy);
489
    T retryOptions(RetryOptions retryOptions);
490
    T addPolicy(HttpPipelinePolicy policy);
491
    T pipeline(HttpPipeline pipeline);
492
    T enableAccountIdentifierLogging();
493
}
494

495
abstract class AadCredentialBuilderBase<T extends AadCredentialBuilderBase<T>> extends CredentialBuilderBase<T> {
496
    T authorityHost(String authorityHost);
497
    T clientId(String clientId);
498
    T tenantId(String tenantId);
499
    T executorService(ExecutorService executorService);
500
    T additionallyAllowedTenants(String... additionallyAllowedTenants);
501
    T additionallyAllowedTenants(List<String> additionallyAllowedTenants);
502
    T disableInstanceDiscovery();
503
    T enableUnsafeSupportLogging();
504
}
505
```
506

507
[Configuration and Utilities](./configuration-and-utilities.md)
508

509
## Exception Handling
510

511
```java { .api }
512
class CredentialUnavailableException extends ClientAuthenticationException {
513
    CredentialUnavailableException(String message);
514
    CredentialUnavailableException(String message, Throwable cause);
515
}
516

517
class AuthenticationRequiredException extends CredentialUnavailableException {
518
    AuthenticationRequiredException(String message, TokenRequestContext request);
519
    AuthenticationRequiredException(String message, TokenRequestContext request, Throwable cause);
520
    TokenRequestContext getTokenRequestContext();
521
}
522
```
523

524
## Types
525

526
```java { .api }
527
// From azure-core - key interface implemented by all credentials
528
interface TokenCredential {
529
    Mono<AccessToken> getToken(TokenRequestContext request);
530
    default AccessToken getTokenSync(TokenRequestContext request);
531
}
532

533
// Token request context specifying the scopes and tenant
534
class TokenRequestContext {
535
    List<String> getScopes();
536
    String getTenantId();
537
    String getClaims();
538
}
539

540
// Access token with expiration information
541
class AccessToken {
542
    String getToken();
543
    OffsetDateTime getExpiresAt();
544
    boolean isExpired();
545
}
546
```