0
# Authentication System
1

2
Comprehensive credential management supporting Azure Active Directory tokens, API keys, SAS tokens, and custom authentication schemes with automatic token refresh and secure credential rotation.
3

4
## Capabilities
5

6
### TokenCredential Interface
7

8
Core interface for obtaining access tokens for Azure Active Directory authentication with support for various scopes and tenant configurations.
9

10
```java { .api }
11
/**
12
 * The interface for credentials that can provide a token.
13
 */
14
@FunctionalInterface
15
interface TokenCredential {
16
    /**
17
     * Asynchronously get a token for a given resource/audience.
18
     * @param request The details of the token request
19
     * @return A Mono containing the access token
20
     */
21
    Mono<AccessToken> getToken(TokenRequestContext request);
22
    
23
    /**
24
     * Synchronously get a token for a given resource/audience.
25
     * @param request The details of the token request  
26
     * @return The access token
27
     */
28
    default AccessToken getTokenSync(TokenRequestContext request) {
29
        return getToken(request).block();
30
    }
31
}
32
```
33

34
### AccessToken
35

36
Immutable access token with token string, expiration time, and refresh time for secure token management.
37

38
```java { .api }
39
/**
40
 * Represents an immutable access token with a token string and an expiration time.
41
 */
42
class AccessToken {
43
    /**
44
     * Creates an access token.
45
     * @param token The token string
46
     * @param expiresAt The token expiration date in UTC
47
     */
48
    public AccessToken(String token, OffsetDateTime expiresAt);
49
    
50
    /**
51
     * Creates an access token.
52
     * @param token The token string
53
     * @param expiresAt The token expiration date in UTC
54
     * @param refreshAt The token refresh date in UTC
55
     */
56
    public AccessToken(String token, OffsetDateTime expiresAt, OffsetDateTime refreshAt);
57
    
58
    /**
59
     * Creates an access token.
60
     * @param token The token string
61
     * @param expiresAt The token expiration date in UTC
62
     * @param refreshAt The token refresh date in UTC  
63
     * @param tokenType The token type ("Bearer" or "Pop")
64
     */
65
    public AccessToken(String token, OffsetDateTime expiresAt, OffsetDateTime refreshAt, String tokenType);
66
    
67
    /**
68
     * Gets the token.
69
     * @return The token string
70
     */
71
    public String getToken();
72
    
73
    /**
74
     * Gets the time when the token expires, in UTC.
75
     * @return The token expiration time
76
     */
77
    public OffsetDateTime getExpiresAt();
78
    
79
    /**
80
     * Gets the time when the token should be refreshed, in UTC.
81
     * @return The token refresh time
82
     */
83
    public OffsetDateTime getRefreshAt();
84
    
85
    /**
86
     * Whether the token has expired.
87
     * @return true if the token has expired, false otherwise
88
     */
89
    public boolean isExpired();
90
    
91
    /**
92
     * Gets the token type.
93
     * @return The token type, typically "Bearer" or "Pop"
94
     */
95
    public String getTokenType();
96
    
97
    /**
98
     * Gets the duration until the token expires.
99
     * @return Duration until expiration
100
     */
101
    public Duration getDurationUntilExpiration();
102
}
103
```
104

105
### TokenRequestContext
106

107
Context for token requests containing scopes, tenant ID, claims, and additional authentication parameters.
108

109
```java { .api }
110
/**
111
 * Contains details of a request to get a token.
112
 */
113
class TokenRequestContext {
114
    /**
115
     * Creates a token request context.
116
     */
117
    public TokenRequestContext();
118
    
119
    /**
120
     * Gets the scopes required by the token.
121
     * @return The scopes required by the token
122
     */
123
    public List<String> getScopes();
124
    
125
    /**
126
     * Sets the scopes required by the token.
127
     * @param scopes The scopes required by the token
128
     * @return The updated TokenRequestContext
129
     */
130
    public TokenRequestContext setScopes(List<String> scopes);
131
    
132
    /**
133
     * Adds scopes to the request.
134
     * @param scopes The scopes to add
135
     * @return The updated TokenRequestContext
136
     */
137
    public TokenRequestContext addScopes(String... scopes);
138
    
139
    /**
140
     * Gets the additional claims to be included in the token.
141
     * @return The additional claims
142
     */
143
    public String getClaims();
144
    
145
    /**
146
     * Sets the additional claims to be included in the token.
147
     * @param claims The additional claims
148
     * @return The updated TokenRequestContext
149
     */
150
    public TokenRequestContext setClaims(String claims);
151
    
152
    /**
153
     * Gets the tenant ID to be used for the authentication request.
154
     * @return The tenant ID
155
     */
156
    public String getTenantId();
157
    
158
    /**
159
     * Sets the tenant ID to be used for the authentication request.
160
     * @param tenantId The tenant ID
161
     * @return The updated TokenRequestContext
162
     */
163
    public TokenRequestContext setTenantId(String tenantId);
164
    
165
    /**
166
     * Indicates whether to enable Continuous Access Evaluation (CAE).
167
     * @return Whether CAE is enabled
168
     */
169
    public boolean isCaeEnabled();
170
    
171
    /**
172
     * Sets whether to enable Continuous Access Evaluation (CAE).
173
     * @param enableCae Whether to enable CAE
174
     * @return The updated TokenRequestContext
175
     */
176
    public TokenRequestContext setCaeEnabled(boolean enableCae);
177
    
178
    /**
179
     * Gets the Proof of Possession options.
180
     * @return The Proof of Possession options
181
     */
182
    public ProofOfPossessionOptions getProofOfPossessionOptions();
183
    
184
    /**
185
     * Sets the Proof of Possession options.
186
     * @param proofOfPossessionOptions The Proof of Possession options
187
     * @return The updated TokenRequestContext
188
     */
189
    public TokenRequestContext setProofOfPossessionOptions(ProofOfPossessionOptions proofOfPossessionOptions);
190
}
191
```
192

193
### KeyCredential
194

195
Base credential class for key-based authentication with secure key rotation support.
196

197
```java { .api }
198
/**
199
 * Represents a credential that uses a key to authenticate to an Azure Service.
200
 */
201
class KeyCredential {
202
    /**
203
     * Creates a credential that authorizes request with the given key.
204
     * @param key The key used to authorize requests
205
     */
206
    public KeyCredential(String key);
207
    
208
    /**
209
     * Retrieves the key associated to this credential.
210
     * @return The key being used for authorization
211
     */
212
    public String getKey();
213
    
214
    /**
215
     * Rotates the key associated to this credential.
216
     * @param key The new key to associated with this credential
217
     * @return The updated KeyCredential object
218
     */
219
    public KeyCredential update(String key);
220
}
221
```
222

223
### AzureKeyCredential
224

225
Azure-specific key credential with enhanced security features and integration with Azure services.
226

227
```java { .api }
228
/**
229
 * Represents a credential that uses an Azure key to authenticate to an Azure Service.
230
 */
231
class AzureKeyCredential extends KeyCredential {
232
    /**
233
     * Creates a credential that authorizes request with the given key.
234
     * @param key The key used to authorize requests
235
     */
236
    public AzureKeyCredential(String key);
237
    
238
    /**
239
     * Rotates the key associated to this credential.
240
     * @param key The new key to associated with this credential  
241
     * @return The updated AzureKeyCredential object
242
     */
243
    public AzureKeyCredential update(String key);
244
}
245
```
246

247
### AzureNamedKeyCredential
248

249
Credential combining key name and key value for services requiring named key authentication.
250

251
```java { .api }
252
/**
253
 * Represents a credential that uses both a key name and key value to authenticate to an Azure Service.
254
 */
255
class AzureNamedKeyCredential {
256
    /**
257
     * Creates a credential with specified key name and key value.
258
     * @param name The key name
259
     * @param key The key value
260
     */
261
    public AzureNamedKeyCredential(String name, String key);
262
    
263
    /**
264
     * Gets the key name.
265
     * @return The key name
266
     */
267
    public String getName();
268
    
269
    /**
270
     * Gets the key value.
271
     * @return The key value
272
     */
273
    public String getKey();
274
    
275
    /**
276
     * Rotates the key associated with this credential.
277
     * @param key The new key value
278
     * @return The updated AzureNamedKeyCredential object
279
     */
280
    public AzureNamedKeyCredential update(String key);
281
    
282
    /**
283
     * Rotates both the key name and key value.
284
     * @param name The new key name
285
     * @param key The new key value
286
     * @return The updated AzureNamedKeyCredential object
287
     */
288
    public AzureNamedKeyCredential update(String name, String key);
289
}
290
```
291

292
### AzureNamedKey
293

294
Immutable key pair containing key name and key value for Azure named key authentication.
295

296
```java { .api }
297
/**
298
 * Represents a credential bag containing the key and the name of the key.
299
 */
300
@Immutable
301
class AzureNamedKey {
302
    /**
303
     * Retrieves the key.
304
     * @return The key
305
     */
306
    public String getKey();
307
    
308
    /**
309
     * Retrieves the name associated with the key.
310
     * @return The name of the key
311
     */
312
    public String getName();
313
}
314
```
315

316
### AzureSasCredential
317

318
Credential for Shared Access Signature (SAS) authentication with automatic signature parsing and validation.
319

320
```java { .api }
321
/**
322
 * Represents a credential that uses a Shared Access Signature to authenticate to an Azure Service.
323
 */
324
class AzureSasCredential {
325
    /**
326
     * Creates a credential that authorizes request with the given shared access signature.
327
     * @param signature The shared access signature used to authorize requests
328
     */
329
    public AzureSasCredential(String signature);
330
    
331
    /**
332
     * Retrieves the shared access signature associated to this credential.
333
     * @return The shared access signature being used for authorization
334
     */
335
    public String getSignature();
336
    
337
    /**
338
     * Rotates the shared access signature associated to this credential.
339
     * @param signature The new shared access signature to associate with this credential
340
     * @return The updated AzureSasCredential object
341
     */
342
    public AzureSasCredential update(String signature);
343
}
344
```
345

346
### BasicAuthenticationCredential
347

348
HTTP Basic authentication credential for username and password authentication.
349

350
```java { .api }
351
/**
352
 * Represents Basic authentication credential.
353
 */
354
class BasicAuthenticationCredential {
355
    /**
356
     * Creates a basic authentication credential.
357
     * @param username The username for authentication
358
     * @param password The password for authentication
359
     */
360
    public BasicAuthenticationCredential(String username, String password);
361
    
362
    /**
363
     * Gets the username.
364
     * @return The username
365
     */
366
    public String getUsername();
367
    
368
    /**
369
     * Gets the password.
370
     * @return The password
371
     */
372
    public String getPassword();
373
    
374
    /**
375
     * Creates the authorization header value for basic authentication.
376
     * @return The authorization header value
377
     */
378
    public String getAuthorizationHeaderValue();
379
}
380
```
381

382
### ProofOfPossessionOptions
383

384
Configuration options for Proof of Possession (PoP) token authentication.
385

386
```java { .api }
387
/**
388
 * Options for Proof of Possession authentication.
389
 */
390
class ProofOfPossessionOptions {
391
    /**
392
     * Creates Proof of Possession options.
393
     */
394
    public ProofOfPossessionOptions();
395
    
396
    /**
397
     * Gets the HTTP method.
398
     * @return HTTP method
399
     */
400
    public String getHttpMethod();
401
    
402
    /**
403
     * Sets the HTTP method.
404
     * @param httpMethod The HTTP method
405
     * @return Updated ProofOfPossessionOptions
406
     */
407
    public ProofOfPossessionOptions setHttpMethod(String httpMethod);
408
    
409
    /**
410
     * Gets the request URL.
411
     * @return Request URL
412
     */
413
    public String getUrl();
414
    
415
    /**
416
     * Sets the request URL.
417
     * @param url The request URL
418
     * @return Updated ProofOfPossessionOptions
419
     */
420
    public ProofOfPossessionOptions setUrl(String url);
421
    
422
    /**
423
     * Gets additional claims.
424
     * @return Map of additional claims
425
     */
426
    public Map<String, Object> getAdditionalClaims();
427
    
428
    /**
429
     * Sets additional claims.
430
     * @param additionalClaims Map of additional claims
431
     * @return Updated ProofOfPossessionOptions
432
     */
433
    public ProofOfPossessionOptions setAdditionalClaims(Map<String, Object> additionalClaims);
434
}
435
```
436

437
### SimpleTokenCache
438

439
Basic token cache implementation for storing and retrieving access tokens.
440

441
```java { .api }
442
/**
443
 * A simple, thread-safe token cache implementation.
444
 */
445
class SimpleTokenCache {
446
    /**
447
     * Creates a new SimpleTokenCache.
448
     */
449
    public SimpleTokenCache();
450
    
451
    /**
452
     * Gets a cached token.
453
     * @param key Cache key
454
     * @return Cached AccessToken or null if not found
455
     */
456
    public AccessToken getToken(String key);
457
    
458
    /**
459
     * Caches a token.
460
     * @param key Cache key  
461
     * @param token Token to cache
462
     */
463
    public void putToken(String key, AccessToken token);
464
    
465
    /**
466
     * Removes a token from cache.
467
     * @param key Cache key
468
     */
469
    public void removeToken(String key);
470
    
471
    /**
472
     * Clears all cached tokens.
473
     */
474
    public void clear();
475
    
476
    /**
477
     * Gets the number of cached tokens.
478
     * @return Number of cached tokens
479
     */
480
    public int size();
481
}
482
```
483

484
### HttpAuthorization
485

486
HTTP Authorization header representation for various authentication schemes.
487

488
```java { .api }
489
/**
490
 * Represents the value of an Authorization header.
491
 */
492
class HttpAuthorization {
493
    /**
494
     * Creates an HttpAuthorization instance.
495
     * @param scheme The authorization scheme (e.g., "Bearer", "Basic")
496
     * @param parameter The authorization parameter (e.g., token, credentials)
497
     */
498
    public HttpAuthorization(String scheme, String parameter);
499
    
500
    /**
501
     * Gets the authorization scheme.
502
     * @return The authorization scheme
503
     */
504
    public String getScheme();
505
    
506
    /**
507
     * Gets the authorization parameter.
508
     * @return The authorization parameter
509
     */
510
    public String getParameter();
511
    
512
    /**
513
     * Gets the full authorization header value.
514
     * @return Authorization header value in format "scheme parameter"
515
     */
516
    @Override
517
    public String toString();
518
    
519
    /**
520
     * Creates a Bearer token authorization.
521
     * @param token The bearer token
522
     * @return HttpAuthorization for bearer token
523
     */
524
    public static HttpAuthorization bearerToken(String token);
525
    
526
    /**
527
     * Creates a Basic authentication authorization.
528
     * @param credentials The base64-encoded credentials
529
     * @return HttpAuthorization for basic auth
530
     */
531
    public static HttpAuthorization basicAuth(String credentials);
532
}
533
```
534

535
## Client Traits
536

537
Builder traits for consistent credential configuration across Azure SDK clients.
538

539
```java { .api }
540
/**
541
 * Trait for Azure SDK client builders that support TokenCredential.
542
 */
543
interface TokenCredentialTrait<T> {
544
    /**
545
     * Sets the TokenCredential used to authorize requests sent by the service client.
546
     * @param credential TokenCredential used to authorize requests
547
     * @return The updated builder object
548
     */
549
    T credential(TokenCredential credential);
550
}
551

552
/**
553
 * Trait for Azure SDK client builders that support AzureKeyCredential.
554
 */
555
interface AzureKeyCredentialTrait<T> {
556
    /**
557
     * Sets the AzureKeyCredential used to authorize requests sent by the service client.
558
     * @param credential AzureKeyCredential used to authorize requests
559
     * @return The updated builder object
560
     */
561
    T credential(AzureKeyCredential credential);
562
}
563

564
/**
565
 * Trait for Azure SDK client builders that support AzureNamedKeyCredential.
566
 */
567
interface AzureNamedKeyCredentialTrait<T> {
568
    /**
569
     * Sets the AzureNamedKeyCredential used to authorize requests sent by the service client.
570
     * @param credential AzureNamedKeyCredential used to authorize requests
571
     * @return The updated builder object
572
     */
573
    T credential(AzureNamedKeyCredential credential);
574
}
575

576
/**
577
 * Trait for Azure SDK client builders that support AzureSasCredential.
578
 */
579
interface AzureSasCredentialTrait<T> {
580
    /**
581
     * Sets the AzureSasCredential used to authorize requests sent by the service client.
582
     * @param credential AzureSasCredential used to authorize requests
583
     * @return The updated builder object
584
     */
585
    T credential(AzureSasCredential credential);
586
}
587

588
/**
589
 * Trait for Azure SDK client builders that support KeyCredential.
590
 */
591
interface KeyCredentialTrait<T> {
592
    /**
593
     * Sets the KeyCredential used to authorize requests sent by the service client.
594
     * @param credential KeyCredential used to authorize requests
595
     * @return The updated builder object
596
     */
597
    T credential(KeyCredential credential);
598
}
599

600
/**
601
 * Trait for Azure SDK client builders that support connection strings.
602
 */
603
interface ConnectionStringTrait<T> {
604
    /**
605
     * Sets the connection string for the service.
606
     * @param connectionString Connection string for the service
607
     * @return The updated builder object
608
     */
609
    T connectionString(String connectionString);
610
}
611
```
612

613
## Usage Examples
614

615
### Using TokenCredential
616

617
```java
618
import com.azure.core.credential.*;
619
import com.azure.identity.DefaultAzureCredentialBuilder;
620

621
// Create a TokenCredential (typically from azure-identity library)
622
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
623

624
// Create token request context
625
TokenRequestContext request = new TokenRequestContext()
626
    .addScopes("https://vault.azure.net/.default")
627
    .setTenantId("tenant-id");
628

629
// Get access token asynchronously
630
Mono<AccessToken> tokenMono = credential.getToken(request);
631
AccessToken token = tokenMono.block();
632

633
// Check token properties
634
System.out.println("Token: " + token.getToken());
635
System.out.println("Expires at: " + token.getExpiresAt());
636
System.out.println("Is expired: " + token.isExpired());
637
```
638

639
### Using Key Credentials
640

641
```java
642
import com.azure.core.credential.*;
643

644
// Azure Key Credential
645
AzureKeyCredential keyCredential = new AzureKeyCredential("your-api-key");
646
System.out.println("Key: " + keyCredential.getKey());
647

648
// Rotate the key
649
keyCredential.update("new-api-key");
650

651
// Azure Named Key Credential  
652
AzureNamedKeyCredential namedKeyCredential = new AzureNamedKeyCredential("keyName", "keyValue");
653
System.out.println("Name: " + namedKeyCredential.getName());
654
System.out.println("Key: " + namedKeyCredential.getKey());
655

656
// Azure SAS Credential
657
String sasToken = "sp=r&st=2023-01-01T00:00:00Z&se=2023-12-31T23:59:59Z&sv=2022-11-02&sr=c&sig=...";
658
AzureSasCredential sasCredential = new AzureSasCredential(sasToken);
659
System.out.println("SAS: " + sasCredential.getSignature());
660
```
661

662
### Using Basic Authentication
663

664
```java
665
import com.azure.core.credential.BasicAuthenticationCredential;
666

667
BasicAuthenticationCredential basicAuth = 
668
    new BasicAuthenticationCredential("username", "password");
669

670
String authHeader = basicAuth.getAuthorizationHeaderValue();
671
System.out.println("Authorization: " + authHeader); // "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
672
```
673

674
### Token Caching
675

676
```java
677
import com.azure.core.credential.*;
678
import java.time.OffsetDateTime;
679

680
SimpleTokenCache cache = new SimpleTokenCache();
681

682
// Cache a token
683
AccessToken token = new AccessToken("token123", OffsetDateTime.now().plusHours(1));
684
cache.putToken("vault-token", token);
685

686
// Retrieve cached token
687
AccessToken cachedToken = cache.getToken("vault-token");
688
if (cachedToken != null && !cachedToken.isExpired()) {
689
    System.out.println("Using cached token: " + cachedToken.getToken());
690
} else {
691
    System.out.println("Token expired or not found, need to refresh");
692
}
693
```
694

695
### Proof of Possession Authentication
696

697
```java
698
import com.azure.core.credential.*;
699

700
ProofOfPossessionOptions popOptions = new ProofOfPossessionOptions()
701
    .setHttpMethod("POST")
702
    .setUrl("https://api.example.com/secure-endpoint")
703
    .setAdditionalClaims(Map.of("aud", "https://api.example.com"));
704

705
TokenRequestContext request = new TokenRequestContext()
706
    .addScopes("https://api.example.com/.default")
707
    .setProofOfPossessionOptions(popOptions);
708

709
// Use with TokenCredential that supports PoP
710
AccessToken popToken = credential.getToken(request).block();
711
```