0
# Credential Providers
1

2
Comprehensive set of credential providers for loading AWS credentials from various sources including environment variables, profiles, containers, and instance metadata with automatic fallback chains.
3

4
## Capabilities
5

6
### DefaultCredentialsProvider
7

8
Default AWS credential provider chain that checks multiple credential sources in order: System Properties → Environment Variables → Web Identity Token → Profile File → Container → Instance Profile.
9

10
```java { .api }
11
/**
12
 * Default credentials provider chain for AWS credentials lookup
13
 * Implements automatic fallback through multiple credential sources
14
 */
15
final class DefaultCredentialsProvider implements AwsCredentialsProvider, SdkAutoCloseable, 
16
                                                  ToCopyableBuilder<Builder, DefaultCredentialsProvider> {
17
    /**
18
     * Create default provider with singleton behavior (DEPRECATED)
19
     * @deprecated Use builder() for better resource management
20
     * @return DefaultCredentialsProvider instance
21
     */
22
    @Deprecated
23
    static DefaultCredentialsProvider create();
24
    
25
    /**
26
     * Create builder for custom configuration
27
     * @return Builder instance
28
     */
29
    static Builder builder();
30
    
31
    AwsCredentials resolveCredentials();
32
    void close();
33
    Builder toBuilder();
34
    
35
    interface Builder extends CopyableBuilder<Builder, DefaultCredentialsProvider> {
36
        /**
37
         * Override profile file location
38
         * @param profileFile profile file supplier
39
         * @return builder instance
40
         */
41
        Builder profileFile(Supplier<ProfileFile> profileFile);
42
        
43
        /**
44
         * Configure profile file using builder
45
         * @param profileFileBuilderConsumer profile file builder configuration
46
         * @return builder instance  
47
         */
48
        Builder profileFile(Consumer<ProfileFile.Builder> profileFileBuilderConsumer);
49
        
50
        /**
51
         * Set specific profile name to use
52
         * @param profileName profile name
53
         * @return builder instance
54
         */
55
        Builder profileName(String profileName);
56
        
57
        /**
58
         * Enable reusing the last successful provider
59
         * @param reuseLastProviderEnabled true to enable reuse
60
         * @return builder instance
61
         */
62
        Builder reuseLastProviderEnabled(Boolean reuseLastProviderEnabled);
63
        
64
        /**
65
         * Enable background credential updates
66
         * @param asyncCredentialUpdateEnabled true to enable async updates
67
         * @return builder instance
68
         */
69
        Builder asyncCredentialUpdateEnabled(Boolean asyncCredentialUpdateEnabled);
70
        
71
        DefaultCredentialsProvider build();
72
    }
73
}
74
```
75

76
**Usage Examples:**
77

78
```java
79
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
80

81
// Use default chain (deprecated singleton)
82
DefaultCredentialsProvider provider = DefaultCredentialsProvider.create();
83

84
// Recommended: Use builder with custom configuration
85
DefaultCredentialsProvider customProvider = DefaultCredentialsProvider.builder()
86
    .profileName("production")
87
    .reuseLastProviderEnabled(true)
88
    .build();
89

90
// Use and properly close
91
try (DefaultCredentialsProvider provider = DefaultCredentialsProvider.builder().build()) {
92
    AwsCredentials credentials = provider.resolveCredentials();
93
    // Use credentials...
94
}
95
```
96

97
### AwsCredentialsProviderChain
98

99
Chains multiple credential providers with fallback behavior, trying each provider in order until one succeeds.
100

101
```java { .api }
102
/**
103
 * Chains multiple credential providers with fallback behavior
104
 * Tries providers in order until one successfully returns credentials
105
 */
106
final class AwsCredentialsProviderChain implements AwsCredentialsProvider, SdkAutoCloseable,
107
                                                   ToCopyableBuilder<Builder, AwsCredentialsProviderChain> {
108
    /**
109
     * Create provider chain from varargs
110
     * @param providers credential providers in order
111
     * @return AwsCredentialsProviderChain instance
112
     */
113
    static AwsCredentialsProviderChain of(AwsCredentialsProvider... providers);
114
    
115
    /**
116
     * Create builder for advanced configuration
117
     * @return Builder instance
118
     */
119
    static Builder builder();
120
    
121
    AwsCredentials resolveCredentials();
122
    void close();
123
    Builder toBuilder();
124
    
125
    interface Builder extends CopyableBuilder<Builder, AwsCredentialsProviderChain> {
126
        /**
127
         * Enable reusing the last successful provider for performance
128
         * @param reuseLastProviderEnabled true to enable reuse
129
         * @return builder instance
130
         */
131
        Builder reuseLastProviderEnabled(Boolean reuseLastProviderEnabled);
132
        
133
        /**
134
         * Set the list of credential providers
135
         * @param credentialsProviders collection of providers
136
         * @return builder instance
137
         */
138
        Builder credentialsProviders(Collection<? extends AwsCredentialsProvider> credentialsProviders);
139
        
140
        /**
141
         * Set credential providers from varargs
142
         * @param credentialsProviders providers to add
143
         * @return builder instance
144
         */
145
        Builder credentialsProviders(AwsCredentialsProvider... credentialsProviders);
146
        
147
        /**
148
         * Add a single credential provider to the chain
149
         * @param credentialsProvider provider to add
150
         * @return builder instance
151
         */
152
        Builder addCredentialsProvider(AwsCredentialsProvider credentialsProvider);
153
        
154
        AwsCredentialsProviderChain build();
155
    }
156
}
157
```
158

159
**Usage Examples:**
160

161
```java
162
import software.amazon.awssdk.auth.credentials.*;
163

164
// Simple chain creation
165
AwsCredentialsProviderChain simpleChain = AwsCredentialsProviderChain.of(
166
    EnvironmentVariableCredentialsProvider.create(),
167
    ProfileCredentialsProvider.create(),
168
    InstanceProfileCredentialsProvider.create()
169
);
170

171
// Advanced chain with performance optimization
172
AwsCredentialsProviderChain optimizedChain = AwsCredentialsProviderChain.builder()
173
    .reuseLastProviderEnabled(true)
174
    .addCredentialsProvider(EnvironmentVariableCredentialsProvider.create())
175
    .addCredentialsProvider(ProfileCredentialsProvider.create("production"))
176
    .addCredentialsProvider(ContainerCredentialsProvider.create())
177
    .addCredentialsProvider(InstanceProfileCredentialsProvider.create())
178
    .build();
179
```
180

181
### StaticCredentialsProvider
182

183
Provider that returns static, pre-configured credentials without any external lookups.
184

185
```java { .api }
186
/**
187
 * Provider that returns static credentials
188
 * Useful for testing or when credentials are known at compile time
189
 */
190
final class StaticCredentialsProvider implements AwsCredentialsProvider {
191
    /**
192
     * Create provider with static credentials
193
     * @param credentials static credentials to return
194
     * @return StaticCredentialsProvider instance
195
     */
196
    static StaticCredentialsProvider create(AwsCredentials credentials);
197
    
198
    AwsCredentials resolveCredentials();
199
}
200
```
201

202
### Environment and System Property Providers
203

204
Providers that load credentials from environment variables and Java system properties.
205

206
#### SystemSettingsCredentialsProvider
207

208
Abstract base class for credential providers that load credentials from system settings (environment variables and system properties).
209

210
```java { .api }
211
/**
212
 * Abstract base class for credential providers that read from system settings
213
 * Provides common functionality for environment and system property providers
214
 */
215
abstract class SystemSettingsCredentialsProvider implements AwsCredentialsProvider {
216
    /**
217
     * Create provider instance (implementation-specific)
218
     * @return SystemSettingsCredentialsProvider instance
219
     */
220
    static SystemSettingsCredentialsProvider create();
221
    
222
    AwsCredentials resolveCredentials();
223
}
224
```
225

226
#### EnvironmentVariableCredentialsProvider
227

228
```java { .api }
229
/**
230
 * Loads credentials from environment variables
231
 * Checks AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
232
 */
233
final class EnvironmentVariableCredentialsProvider implements AwsCredentialsProvider {
234
    static EnvironmentVariableCredentialsProvider create();
235
    AwsCredentials resolveCredentials();
236
}
237

238
/**
239
 * Loads credentials from Java system properties
240
 * Checks aws.accessKeyId, aws.secretAccessKey, aws.sessionToken
241
 */
242
final class SystemPropertyCredentialsProvider implements AwsCredentialsProvider {
243
    static SystemPropertyCredentialsProvider create();
244
    AwsCredentials resolveCredentials();
245
}
246
```
247

248
### ProfileCredentialsProvider
249

250
Loads credentials from AWS profile files (~/.aws/credentials and ~/.aws/config).
251

252
```java { .api }
253
/**
254
 * Loads credentials from AWS profile files
255
 * Supports profiles, role assumption, and SSO configurations
256
 */
257
final class ProfileCredentialsProvider implements AwsCredentialsProvider, SdkAutoCloseable,
258
                                                  ToCopyableBuilder<Builder, ProfileCredentialsProvider> {
259
    /**
260
     * Create provider for default profile
261
     * @return ProfileCredentialsProvider instance
262
     */
263
    static ProfileCredentialsProvider create();
264
    
265
    /**
266
     * Create provider for specific profile
267
     * @param profileName name of profile to use
268
     * @return ProfileCredentialsProvider instance
269
     */
270
    static ProfileCredentialsProvider create(String profileName);
271
    
272
    /**
273
     * Create builder for advanced configuration
274
     * @return Builder instance
275
     */
276
    static Builder builder();
277
    
278
    AwsCredentials resolveCredentials();
279
    void close();
280
    Builder toBuilder();
281
    
282
    interface Builder extends CopyableBuilder<Builder, ProfileCredentialsProvider> {
283
        /**
284
         * Override profile file location
285
         * @param profileFile profile file supplier
286
         * @return builder instance
287
         */
288
        Builder profileFile(Supplier<ProfileFile> profileFile);
289
        
290
        /**
291
         * Configure profile file using builder
292
         * @param profileFileBuilderConsumer profile file builder configuration
293
         * @return builder instance
294
         */
295
        Builder profileFile(Consumer<ProfileFile.Builder> profileFileBuilderConsumer);
296
        
297
        /**
298
         * Set profile name to use
299
         * @param profileName profile name
300
         * @return builder instance
301
         */
302
        Builder profileName(String profileName);
303
        
304
        ProfileCredentialsProvider build();
305
    }
306
}
307
```
308

309
### HTTP-Based Providers
310

311
Providers that retrieve credentials from HTTP endpoints like EC2 instance metadata and container metadata services.
312

313
```java { .api }
314
/**
315
 * Base interface for HTTP-based credential providers
316
 * Provides common configuration for endpoint and async behavior
317
 */
318
interface HttpCredentialsProvider extends AwsCredentialsProvider, SdkAutoCloseable {
319
    interface Builder<B extends Builder<B, T>, T extends HttpCredentialsProvider> 
320
            extends CopyableBuilder<B, T> {
321
        /**
322
         * Enable background credential refresh
323
         * @param asyncCredentialUpdateEnabled true to enable
324
         * @return builder instance
325
         */
326
        B asyncCredentialUpdateEnabled(Boolean asyncCredentialUpdateEnabled);
327
        
328
        /**
329
         * Set thread name for async operations
330
         * @param asyncThreadName thread name
331
         * @return builder instance
332
         */
333
        B asyncThreadName(String asyncThreadName);
334
        
335
        /**
336
         * Override default endpoint URL
337
         * @param endpoint endpoint URL
338
         * @return builder instance
339
         */
340
        B endpoint(String endpoint);
341
    }
342
}
343

344
/**
345
 * Loads credentials from EC2 Instance Metadata Service (IMDS)
346
 * Uses IMDSv2 by default with fallback to IMDSv1
347
 */
348
final class InstanceProfileCredentialsProvider implements HttpCredentialsProvider,
349
                                                          ToCopyableBuilder<Builder, InstanceProfileCredentialsProvider> {
350
    static InstanceProfileCredentialsProvider create();
351
    static Builder builder();
352
    
353
    interface Builder extends HttpCredentialsProvider.Builder<Builder, InstanceProfileCredentialsProvider> {
354
        /**
355
         * Configure profile file for IMDS settings
356
         * @param profileFile profile file supplier
357
         * @return builder instance
358
         */
359
        Builder profileFile(Supplier<ProfileFile> profileFile);
360
        
361
        /**
362
         * Set profile name for IMDS configuration
363
         * @param profileName profile name
364
         * @return builder instance
365
         */
366
        Builder profileName(String profileName);
367
    }
368
}
369

370
/**
371
 * Loads credentials from container metadata service (ECS, Greengrass)
372
 * Uses AWS_CONTAINER_CREDENTIALS_RELATIVE_URI or AWS_CONTAINER_CREDENTIALS_FULL_URI
373
 */
374
final class ContainerCredentialsProvider implements HttpCredentialsProvider,
375
                                                    ToCopyableBuilder<Builder, ContainerCredentialsProvider> {
376
    static ContainerCredentialsProvider create();
377
    static Builder builder();
378
    
379
    interface Builder extends HttpCredentialsProvider.Builder<Builder, ContainerCredentialsProvider> {
380
    }
381
}
382
```
383

384
### Specialized Providers
385

386
Additional providers for specific use cases like external processes and web identity tokens.
387

388
```java { .api }
389
/**
390
 * Loads credentials from external process
391
 * Executes command specified in profile's credential_process
392
 */
393
class ProcessCredentialsProvider implements AwsCredentialsProvider, SdkAutoCloseable {
394
    static Builder builder();
395
    
396
    interface Builder extends CopyableBuilder<Builder, ProcessCredentialsProvider> {
397
        Builder command(String command);
398
        Builder credentialRefreshThreshold(Duration credentialRefreshThreshold);
399
        Builder processOutputLimit(Long processOutputLimit);
400
        ProcessCredentialsProvider build();
401
    }
402
}
403

404
/**
405
 * Loads credentials using OIDC web identity token from file  
406
 * Used for service accounts and federated access
407
 */
408
class WebIdentityTokenFileCredentialsProvider implements AwsCredentialsProvider, SdkAutoCloseable {
409
    static Builder builder();
410
    
411
    interface Builder extends CopyableBuilder<Builder, WebIdentityTokenFileCredentialsProvider> {
412
        Builder roleArn(String roleArn);
413
        Builder roleSessionName(String roleSessionName);
414
        Builder webIdentityTokenFile(String webIdentityTokenFile);
415
        WebIdentityTokenFileCredentialsProvider build();
416
    }
417
}
418

419
/**
420
 * Provides anonymous (no-auth) credentials
421
 * Used for public resources that don't require authentication
422
 */
423
final class AnonymousCredentialsProvider implements AwsCredentialsProvider {
424
    static AnonymousCredentialsProvider create();
425
    AwsCredentials resolveCredentials();
426
}
427
```
428

429
**Usage Examples:**
430

431
```java
432
import software.amazon.awssdk.auth.credentials.*;
433

434
// EC2 instance credentials with custom configuration
435
InstanceProfileCredentialsProvider instanceProvider = 
436
    InstanceProfileCredentialsProvider.builder()
437
        .asyncCredentialUpdateEnabled(true)
438
        .build();
439

440
// Container credentials for ECS tasks
441
ContainerCredentialsProvider containerProvider = ContainerCredentialsProvider.create();
442

443
// Process credentials from external command
444
ProcessCredentialsProvider processProvider = ProcessCredentialsProvider.builder()
445
    .command("/usr/local/bin/get-aws-credentials")
446
    .build();
447

448
// Web identity token for service accounts
449
WebIdentityTokenFileCredentialsProvider webIdentityProvider = 
450
    WebIdentityTokenFileCredentialsProvider.builder()
451
        .roleArn("arn:aws:iam::123456789012:role/MyRole")
452
        .roleSessionName("MySession")
453
        .webIdentityTokenFile("/var/run/secrets/token")
454
        .build();
455

456
// Anonymous credentials for public resources
457
AnonymousCredentialsProvider anonymousProvider = AnonymousCredentialsProvider.create();
458
```
459

460
## Factory Classes
461

462
Utility classes for creating credential providers with shared configuration.
463

464
```java { .api }
465
/**
466
 * Factory for creating profile-based credential providers
467
 */
468
class ProfileCredentialsProviderFactory {
469
    AwsCredentialsProvider create(String profileName);
470
}
471

472
/**
473
 * Factory for creating child profile credential providers
474
 */
475
class ChildProfileCredentialsProviderFactory {
476
    AwsCredentialsProvider create(ProfileFile profileFile, String profileName);
477
}
478

479
/**
480
 * Factory for creating web identity token credential providers
481
 */
482
class WebIdentityTokenCredentialsProviderFactory {
483
    AwsCredentialsProvider create(String roleArn, String roleSessionName, String webIdentityTokenFile);
484
}
485
```
486

487
### ProfileProviderCredentialsContext
488

489
Context class for providing configuration and dependencies to profile-based credential providers.
490

491
```java { .api }
492
/**
493
 * Context class for profile-based credential provider construction
494
 * Provides configuration and dependencies required by profile providers
495
 */
496
final class ProfileProviderCredentialsContext implements ToCopyableBuilder<Builder, ProfileProviderCredentialsContext> {
497
    /**
498
     * Create builder for context configuration
499
     * @return Builder instance
500
     */
501
    static Builder builder();
502
    
503
    Builder toBuilder();
504
    
505
    interface Builder extends CopyableBuilder<Builder, ProfileProviderCredentialsContext> {
506
        /**
507
         * Set profile file supplier
508
         * @param profileFile profile file supplier
509
         * @return builder instance
510
         */
511
        Builder profileFile(Supplier<ProfileFile> profileFile);
512
        
513
        /**
514
         * Set profile name
515
         * @param profileName profile name to use
516
         * @return builder instance  
517
         */
518
        Builder profileName(String profileName);
519
        
520
        ProfileProviderCredentialsContext build();
521
    }
522
}
523
```
524

525
## Error Handling
526

527
Credential providers may encounter various error conditions:
528

529
```java
530
try {
531
    AwsCredentials credentials = provider.resolveCredentials();
532
} catch (SdkClientException e) {
533
    // Credential resolution failed - check cause for specific error
534
    if (e.getCause() instanceof FileNotFoundException) {
535
        // Profile file not found
536
    } else if (e.getCause() instanceof IOException) {
537
        // Network error accessing metadata service
538
    }
539
}
540
```
541

542
Common error scenarios:
543
- **Profile not found**: Specified profile doesn't exist in configuration files
544
- **Network timeouts**: Instance/container metadata services unreachable
545
- **Permission denied**: Insufficient permissions to access credential sources
546
- **Expired tokens**: Session credentials or web identity tokens have expired
547
- **Malformed responses**: Invalid JSON or format from credential sources