0
# Token Authentication
1

2
OAuth and Bearer token authentication support for modern AWS services requiring token-based authentication flows, including SSO and federated access scenarios.
3

4
## Capabilities
5

6
### SdkToken Interface
7

8
Base interface for SDK tokens providing token value and expiration information.
9

10
```java { .api }
11
/**
12
 * Base interface for SDK tokens used in OAuth-based authentication
13
 * Provides token value and optional expiration time
14
 */
15
interface SdkToken extends TokenIdentity {
16
    /**
17
     * Get the token value
18
     * @return token string
19
     */
20
    String token();
21
    
22
    /**
23
     * Get token expiration time if available
24
     * @return Optional expiration instant
25
     */
26
    Optional<Instant> expirationTime();
27
    
28
    /**
29
     * Get the provider name that created this token
30
     * @return Optional provider name
31
     */
32
    Optional<String> providerName();
33
    
34
    /**
35
     * Get associated account ID if available
36
     * @return Optional account ID
37
     */
38
    Optional<String> accountId();
39
}
40
```
41

42
### SdkTokenProvider Interface
43

44
Functional interface for loading SDK tokens with support for both synchronous and asynchronous resolution.
45

46
```java { .api }
47
/**
48
 * Functional interface for loading SDK tokens
49
 * Supports both sync and async token resolution
50
 */
51
@FunctionalInterface
52
interface SdkTokenProvider extends IdentityProvider<TokenIdentity> {
53
    /**
54
     * Resolve token synchronously
55
     * @return SdkToken instance
56
     * @throws SdkClientException if token cannot be resolved
57
     */
58
    SdkToken resolveToken();
59
    
60
    /**
61
     * Return the identity type this provider handles
62
     * @return Class representing TokenIdentity
63
     */
64
    default Class<TokenIdentity> identityType() {
65
        return TokenIdentity.class;
66
    }
67
    
68
    /**
69
     * Resolve token asynchronously
70
     * @param request resolve identity request
71
     * @return CompletableFuture with resolved identity
72
     */
73
    default CompletableFuture<? extends TokenIdentity> resolveIdentity(ResolveIdentityRequest request) {
74
        return CompletableFuture.supplyAsync(() -> resolveToken());
75
    }
76
}
77
```
78

79
### StaticTokenProvider
80

81
Token provider that returns a static, pre-configured token without any external lookups.
82

83
```java { .api }
84
/**
85
 * Token provider that returns static token
86
 * Useful for testing or when token is known at compile time
87
 */
88
final class StaticTokenProvider implements SdkTokenProvider {
89
    /**
90
     * Create provider with static token
91
     * @param token static token to return
92
     * @return StaticTokenProvider instance
93
     */
94
    static StaticTokenProvider create(SdkToken token);
95
    
96
    SdkToken resolveToken();
97
}
98
```
99

100
**Usage Examples:**
101

102
```java
103
import software.amazon.awssdk.auth.token.credentials.*;
104
import java.time.Instant;
105

106
// Create a custom token implementation
107
SdkToken myToken = new SdkToken() {
108
    @Override
109
    public String token() {
110
        return "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";
111
    }
112
    
113
    @Override
114
    public Optional<Instant> expirationTime() {
115
        return Optional.of(Instant.now().plusSeconds(3600));
116
    }
117
    
118
    @Override
119
    public Optional<String> providerName() {
120
        return Optional.of("MyTokenProvider");
121
    }
122
    
123
    @Override
124
    public Optional<String> accountId() {
125
        return Optional.of("123456789012");
126
    }
127
};
128

129
// Create static provider
130
StaticTokenProvider provider = StaticTokenProvider.create(myToken);
131
SdkToken resolvedToken = provider.resolveToken();
132
```
133

134
### SdkTokenProviderChain
135

136
Chains multiple token providers with fallback behavior, trying each provider in order until one succeeds.
137

138
```java { .api }
139
/**
140
 * Chains multiple token providers with fallback behavior
141
 * Tries providers in order until one successfully returns a token
142
 */
143
class SdkTokenProviderChain implements SdkTokenProvider, SdkAutoCloseable {
144
    /**
145
     * Create provider chain from varargs
146
     * @param providers token providers in order
147
     * @return SdkTokenProviderChain instance
148
     */
149
    static SdkTokenProviderChain of(SdkTokenProvider... providers);
150
    
151
    /**
152
     * Create builder for advanced configuration
153
     * @return Builder instance
154
     */
155
    static Builder builder();
156
    
157
    SdkToken resolveToken();
158
    void close();
159
    
160
    interface Builder extends CopyableBuilder<Builder, SdkTokenProviderChain> {
161
        /**
162
         * Set the list of token providers
163
         * @param tokenProviders collection of providers
164
         * @return builder instance
165
         */
166
        Builder tokenProviders(Collection<? extends SdkTokenProvider> tokenProviders);
167
        
168
        /**
169
         * Set token providers from varargs
170
         * @param tokenProviders providers to add
171
         * @return builder instance
172
         */
173
        Builder tokenProviders(SdkTokenProvider... tokenProviders);
174
        
175
        /**
176
         * Add a single token provider to the chain
177
         * @param tokenProvider provider to add
178
         * @return builder instance
179
         */
180
        Builder addTokenProvider(SdkTokenProvider tokenProvider);
181
        
182
        SdkTokenProviderChain build();
183
    }
184
}
185
```
186

187
### DefaultAwsTokenProvider
188

189
Default AWS token provider chain that checks multiple token sources in order, including profile-based SSO tokens.
190

191
```java { .api }
192
/**
193
 * Default token provider chain for AWS token resolution
194
 * Checks profile-based SSO configurations and other token sources
195
 */
196
final class DefaultAwsTokenProvider implements SdkTokenProvider, SdkAutoCloseable {
197
    /**
198
     * Create default token provider
199
     * @return DefaultAwsTokenProvider instance
200
     */
201
    static DefaultAwsTokenProvider create();
202
    
203
    /**
204
     * Create builder for custom configuration
205
     * @return Builder instance
206
     */
207
    static Builder builder();
208
    
209
    SdkToken resolveToken();
210
    void close();
211
    
212
    interface Builder extends CopyableBuilder<Builder, DefaultAwsTokenProvider> {
213
        /**
214
         * Override profile file location
215
         * @param profileFile profile file supplier
216
         * @return builder instance
217
         */
218
        Builder profileFile(Supplier<ProfileFile> profileFile);
219
        
220
        /**
221
         * Set specific profile name to use
222
         * @param profileName profile name
223
         * @return builder instance
224
         */
225
        Builder profileName(String profileName);
226
        
227
        DefaultAwsTokenProvider build();
228
    }
229
}
230
```
231

232
**Usage Examples:**
233

234
```java
235
import software.amazon.awssdk.auth.token.credentials.aws.DefaultAwsTokenProvider;
236

237
// Use default token provider (for SSO)
238
try (DefaultAwsTokenProvider provider = DefaultAwsTokenProvider.create()) {
239
    SdkToken token = provider.resolveToken();
240
    // Use token for authenticated requests
241
}
242

243
// Custom configuration for specific profile
244
try (DefaultAwsTokenProvider provider = DefaultAwsTokenProvider.builder()
245
        .profileName("sso-profile")
246
        .build()) {
247
    SdkToken token = provider.resolveToken();
248
}
249
```
250

251
### ProfileTokenProvider
252

253
Loads tokens from AWS profile files, particularly useful for SSO (Single Sign-On) configurations.
254

255
```java { .api }
256
/**
257
 * Loads tokens from AWS profile files
258
 * Primarily used for SSO token configurations
259
 */
260
class ProfileTokenProvider implements SdkTokenProvider, SdkAutoCloseable {
261
    /**
262
     * Create provider for default profile
263
     * @return ProfileTokenProvider instance
264
     */
265
    static ProfileTokenProvider create();
266
    
267
    /**
268
     * Create provider for specific profile
269
     * @param profileName name of profile to use
270
     * @return ProfileTokenProvider instance
271
     */
272
    static ProfileTokenProvider create(String profileName);
273
    
274
    /**
275
     * Create builder for advanced configuration
276
     * @return Builder instance
277
     */
278
    static Builder builder();
279
    
280
    SdkToken resolveToken();
281
    void close();
282
    
283
    interface Builder extends CopyableBuilder<Builder, ProfileTokenProvider> {
284
        /**
285
         * Override profile file location
286
         * @param profileFile profile file supplier
287
         * @return builder instance
288
         */
289
        Builder profileFile(Supplier<ProfileFile> profileFile);
290
        
291
        /**
292
         * Set profile name to use
293
         * @param profileName profile name
294
         * @return builder instance
295
         */
296
        Builder profileName(String profileName);
297
        
298
        ProfileTokenProvider build();
299
    }
300
}
301
```
302

303
**Usage Examples:**
304

305
```java
306
import software.amazon.awssdk.auth.token.credentials.ProfileTokenProvider;
307

308
// Load token from default profile
309
try (ProfileTokenProvider provider = ProfileTokenProvider.create()) {
310
    SdkToken token = provider.resolveToken();
311
}
312

313
// Load token from specific SSO profile
314
try (ProfileTokenProvider provider = ProfileTokenProvider.create("my-sso-profile")) {
315
    SdkToken token = provider.resolveToken();
316
    
317
    // Check token expiration
318
    if (token.expirationTime().isPresent()) {
319
        Instant expiry = token.expirationTime().get();
320
        if (expiry.isBefore(Instant.now().plusMinutes(5))) {
321
            // Token expires soon, consider refreshing
322
            logger.warn("Token expires in less than 5 minutes");
323
        }
324
    }
325
}
326
```
327

328
## Factory Classes
329

330
Utility classes for creating token providers with shared configuration.
331

332
```java { .api }
333
/**
334
 * Factory for creating child profile token providers
335
 */
336
class ChildProfileTokenProviderFactory {
337
    /**
338
     * Create token provider for child profile
339
     * @param profileFile profile file containing configuration
340
     * @param profileName name of profile to use
341
     * @return SdkTokenProvider instance
342
     */
343
    SdkTokenProvider create(ProfileFile profileFile, String profileName);
344
}
345

346
/**
347
 * Properties for configuring token provider factories
348
 */
349
class SdkTokenProviderFactoryProperties {
350
    /**
351
     * Get profile file supplier
352
     * @return profile file supplier
353
     */
354
    Supplier<ProfileFile> profileFile();
355
    
356
    /**
357
     * Get profile name
358
     * @return profile name
359
     */
360
    String profileName();
361
}
362
```
363

364
## Token Signing
365

366
Legacy Bearer token signer implementation (deprecated in favor of http-auth module).
367

368
```java { .api }
369
/**
370
 * Signer for Bearer token authorization (RFC 6750)
371
 * @deprecated Use BearerHttpSigner from 'http-auth' module instead
372
 */
373
@Deprecated
374
final class BearerTokenSigner implements Signer {
375
    /**
376
     * Create bearer token signer
377
     * @return BearerTokenSigner instance
378
     */
379
    static BearerTokenSigner create();
380
    
381
    /**
382
     * Sign request with token parameters
383
     * @param request HTTP request to sign
384
     * @param tokenSignerParams token signing parameters
385
     * @return signed HTTP request
386
     */
387
    SdkHttpFullRequest sign(SdkHttpFullRequest request, TokenSignerParams tokenSignerParams);
388
    
389
    /**
390
     * Sign request using execution attributes
391
     * @param request HTTP request to sign
392
     * @param executionAttributes execution context attributes
393
     * @return signed HTTP request
394
     */
395
    SdkHttpFullRequest sign(SdkHttpFullRequest request, ExecutionAttributes executionAttributes);
396
}
397

398
/**
399
 * Token-specific execution attributes for signing context
400
 */
401
class SdkTokenExecutionAttribute {
402
    /**
403
     * Execution attribute for SDK token
404
     */
405
    ExecutionAttribute<SdkToken> SDK_TOKEN;
406
}
407
```
408

409
## SSO Integration
410

411
Token providers integrate with AWS SSO for seamless single sign-on experiences:
412

413
**Profile Configuration Example:**
414
```ini
415
[profile my-sso-profile]
416
sso_start_url = https://my-sso-portal.awsapps.com/start
417
sso_region = us-east-1
418
sso_account_id = 123456789012
419
sso_role_name = MyRole
420
region = us-west-2
421
```
422

423
**Usage with SSO:**
424
```java
425
// Token provider automatically handles SSO token refresh
426
DefaultAwsTokenProvider ssoProvider = DefaultAwsTokenProvider.builder()
427
    .profileName("my-sso-profile")
428
    .build();
429

430
try {
431
    SdkToken token = ssoProvider.resolveToken();
432
    // Token is automatically obtained from SSO cache or triggers SSO flow
433
} catch (SdkClientException e) {
434
    if (e.getMessage().contains("SSO")) {
435
        // May need to run 'aws sso login' command
436
        logger.info("SSO login required: aws sso login --profile my-sso-profile");
437
    }
438
}
439
```
440

441
## Error Handling
442

443
Token resolution may encounter various error conditions:
444

445
```java
446
try {
447
    SdkToken token = provider.resolveToken();
448
} catch (SdkClientException e) {
449
    // Token resolution failed - check cause for specific error
450
    if (e.getMessage().contains("expired")) {
451
        // Token or SSO session expired
452
    } else if (e.getMessage().contains("not found")) {
453
        // Profile or token cache not found
454
    }
455
}
456
```
457

458
Common error scenarios:
459
- **SSO session expired**: Need to re-authenticate with SSO provider
460
- **Profile not found**: Specified profile doesn't exist in configuration files
461
- **Token cache missing**: SSO tokens not cached, may need to login
462
- **Network errors**: Unable to reach SSO endpoints for token refresh
463
- **Permission denied**: Insufficient permissions for SSO role assumption
464

465
## Utility Classes
466

467
### TokenUtils Class
468

469
Utility class providing helper methods for working with SDK tokens and token providers.
470

471
```java { .api }
472
/**
473
 * Utility class for SDK token operations
474
 * Provides conversion and validation methods for token-based authentication
475
 */
476
final class TokenUtils {
477
    /**
478
     * Convert TokenIdentity to SdkToken
479
     * @param tokenIdentity token identity to convert
480
     * @return SdkToken instance
481
     */
482
    static SdkToken toSdkToken(TokenIdentity tokenIdentity);
483
    
484
    /**
485
     * Convert generic identity provider to SDK token provider
486
     * @param identityProvider generic identity provider for tokens
487
     * @return SdkTokenProvider instance
488
     */
489
    static SdkTokenProvider toSdkTokenProvider(
490
        IdentityProvider<? extends TokenIdentity> identityProvider);
491
}
492
```
493

494
**Usage Examples:**
495

496
```java
497
import software.amazon.awssdk.auth.token.credentials.TokenUtils;
498

499
// Convert identity to SDK token
500
TokenIdentity identity = // ... obtain token identity
501
SdkToken sdkToken = TokenUtils.toSdkToken(identity);
502

503
// Convert identity provider to SDK token provider
504
IdentityProvider<TokenIdentity> genericProvider = // ... 
505
SdkTokenProvider tokenProvider = TokenUtils.toSdkTokenProvider(genericProvider);
506

507
// Use converted token provider
508
SdkToken token = tokenProvider.resolveToken();
509
System.out.println("Token: " + token.token());
510
```