0
# Credential Providers
1

2
The STS credential providers offer high-level abstractions for obtaining and managing temporary AWS credentials. They automatically handle credential caching, refresh, and lifecycle management, integrating seamlessly with the AWS SDK credential provider chain.
3

4
## Core Imports
5

6
```java
7
import software.amazon.awssdk.services.sts.auth.*;
8
import software.amazon.awssdk.services.sts.model.*;
9
import software.amazon.awssdk.auth.credentials.AwsCredentials;
10
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
11
import software.amazon.awssdk.core.SdkAutoCloseable;
12
import java.time.Duration;
13
import java.nio.file.Path;
14
import java.util.function.Consumer;
15
import java.util.function.Supplier;
16
```
17

18
## Base Credential Provider
19

20
### StsCredentialsProvider
21

22
Abstract base class for all STS-based credential providers.
23

24
```java { .api }
25
public abstract class StsCredentialsProvider implements AwsCredentialsProvider, SdkAutoCloseable {
26
    public abstract AwsCredentials resolveCredentials();
27
    public void close();
28
    public Duration staleTime();
29
    public Duration prefetchTime();
30
    
31
    public abstract static class BaseBuilder<B extends BaseBuilder<B, T>, T extends ToCopyableBuilder<B, T>> {
32
        public B stsClient(StsClient stsClient);
33
        public B asyncCredentialUpdateEnabled(Boolean asyncCredentialUpdateEnabled);
34
        public B staleTime(Duration staleTime);
35
        public B prefetchTime(Duration prefetchTime);
36
    }
37
}
38
```
39

40
### Configuration Options
41

42
- **staleTime**: Time before credentials are considered stale (default: 1 minute)
43
- **prefetchTime**: Time before expiration to start refreshing credentials (default: 5 minutes)
44
- **asyncCredentialUpdateEnabled**: Enable asynchronous credential refresh (default: false)
45

46
## Assume Role Credential Provider
47

48
### StsAssumeRoleCredentialsProvider
49

50
Provides credentials by assuming an IAM role using the AssumeRole operation.
51

52
```java { .api }
53
public final class StsAssumeRoleCredentialsProvider extends StsCredentialsProvider
54
    implements ToCopyableBuilder<StsAssumeRoleCredentialsProvider.Builder, StsAssumeRoleCredentialsProvider> {
55
    
56
    public static Builder builder();
57
    
58
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsAssumeRoleCredentialsProvider> {
59
        Builder refreshRequest(AssumeRoleRequest assumeRoleRequest);
60
        Builder refreshRequest(Supplier<AssumeRoleRequest> assumeRoleRequestSupplier);
61
        Builder refreshRequest(Consumer<AssumeRoleRequest.Builder> assumeRoleRequest);
62
        StsAssumeRoleCredentialsProvider build();
63
    }
64
}
65
```
66

67
#### Usage Example
68

69
```java
70
StsAssumeRoleCredentialsProvider credentialsProvider = 
71
    StsAssumeRoleCredentialsProvider.builder()
72
        .refreshRequest(AssumeRoleRequest.builder()
73
            .roleArn("arn:aws:iam::123456789012:role/MyRole")
74
            .roleSessionName("MySession")
75
            .durationSeconds(3600)
76
            .build())
77
        .staleTime(Duration.ofMinutes(2))
78
        .prefetchTime(Duration.ofMinutes(10))
79
        .build();
80

81
AwsCredentials credentials = credentialsProvider.resolveCredentials();
82
```
83

84
## Web Identity Credential Providers
85

86
### StsAssumeRoleWithWebIdentityCredentialsProvider
87

88
Provides credentials by assuming an IAM role using web identity tokens (OAuth, OpenID Connect).
89

90
```java { .api }
91
public final class StsAssumeRoleWithWebIdentityCredentialsProvider extends StsCredentialsProvider
92
    implements ToCopyableBuilder<StsAssumeRoleWithWebIdentityCredentialsProvider.Builder, StsAssumeRoleWithWebIdentityCredentialsProvider> {
93
    
94
    public static Builder builder();
95
    
96
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsAssumeRoleWithWebIdentityCredentialsProvider> {
97
        Builder refreshRequest(AssumeRoleWithWebIdentityRequest assumeRoleWithWebIdentityRequest);
98
        Builder refreshRequest(Supplier<AssumeRoleWithWebIdentityRequest> assumeRoleWithWebIdentityRequestSupplier);
99
        Builder refreshRequest(Consumer<AssumeRoleWithWebIdentityRequest.Builder> assumeRoleWithWebIdentityRequest);
100
        StsAssumeRoleWithWebIdentityCredentialsProvider build();
101
    }
102
}
103
```
104

105
### StsWebIdentityTokenFileCredentialsProvider
106

107
Reads web identity tokens from a file and uses them to assume a role.
108

109
```java { .api }
110
public final class StsWebIdentityTokenFileCredentialsProvider extends StsCredentialsProvider
111
    implements ToCopyableBuilder<StsWebIdentityTokenFileCredentialsProvider.Builder, StsWebIdentityTokenFileCredentialsProvider> {
112
    
113
    public static Builder builder();
114
    
115
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsWebIdentityTokenFileCredentialsProvider> {
116
        Builder stsClient(StsClient stsClient);
117
        Builder roleArn(String roleArn);
118
        Builder roleSessionName(String roleSessionName);
119
        Builder webIdentityTokenFile(Path webIdentityTokenFile);
120
        Builder refreshRequest(AssumeRoleWithWebIdentityRequest assumeRoleWithWebIdentityRequest);
121
        Builder refreshRequest(Supplier<AssumeRoleWithWebIdentityRequest> assumeRoleWithWebIdentityRequestSupplier);
122
        Builder refreshRequest(Consumer<AssumeRoleWithWebIdentityRequest.Builder> assumeRoleWithWebIdentityRequest);
123
        StsWebIdentityTokenFileCredentialsProvider build();
124
    }
125
}
126
```
127

128
#### Usage Example
129

130
```java
131
StsWebIdentityTokenFileCredentialsProvider credentialsProvider = 
132
    StsWebIdentityTokenFileCredentialsProvider.builder()
133
        .roleArn("arn:aws:iam::123456789012:role/WebIdentityRole")
134
        .roleSessionName("WebIdentitySession")
135
        .webIdentityTokenFile(Paths.get("/tmp/web-identity-token"))
136
        .build();
137

138
AwsCredentials credentials = credentialsProvider.resolveCredentials();
139
```
140

141
## SAML Credential Provider
142

143
### StsAssumeRoleWithSamlCredentialsProvider
144

145
Provides credentials by assuming an IAM role using SAML assertions.
146

147
```java { .api }
148
public final class StsAssumeRoleWithSamlCredentialsProvider extends StsCredentialsProvider
149
    implements ToCopyableBuilder<StsAssumeRoleWithSamlCredentialsProvider.Builder, StsAssumeRoleWithSamlCredentialsProvider> {
150
    
151
    public static Builder builder();
152
    
153
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsAssumeRoleWithSamlCredentialsProvider> {
154
        Builder refreshRequest(AssumeRoleWithSAMLRequest assumeRoleWithSAMLRequest);
155
        Builder refreshRequest(Supplier<AssumeRoleWithSAMLRequest> assumeRoleWithSAMLRequestSupplier);
156
        Builder refreshRequest(Consumer<AssumeRoleWithSAMLRequest.Builder> assumeRoleWithSAMLRequest);
157
        StsAssumeRoleWithSamlCredentialsProvider build();
158
    }
159
}
160
```
161

162
## Federation Token Credential Provider
163

164
### StsGetFederationTokenCredentialsProvider
165

166
Provides credentials by obtaining federation tokens for temporary access.
167

168
```java { .api }
169
public class StsGetFederationTokenCredentialsProvider extends StsCredentialsProvider
170
    implements ToCopyableBuilder<StsGetFederationTokenCredentialsProvider.Builder, StsGetFederationTokenCredentialsProvider> {
171
    
172
    public static Builder builder();
173
    
174
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsGetFederationTokenCredentialsProvider> {
175
        Builder refreshRequest(GetFederationTokenRequest getFederationTokenRequest);
176
        Builder refreshRequest(Consumer<GetFederationTokenRequest.Builder> getFederationTokenRequest);
177
        StsGetFederationTokenCredentialsProvider build();
178
    }
179
}
180
```
181

182
#### Usage Example
183

184
```java
185
StsGetFederationTokenCredentialsProvider credentialsProvider = 
186
    StsGetFederationTokenCredentialsProvider.builder()
187
        .refreshRequest(GetFederationTokenRequest.builder()
188
            .name("FederatedUser")
189
            .policy("{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":\"s3:*\",\"Resource\":\"*\"}]}")
190
            .durationSeconds(3600)
191
            .build())
192
        .build();
193

194
AwsCredentials credentials = credentialsProvider.resolveCredentials();
195
```
196

197
## Session Token Credential Provider
198

199
### StsGetSessionTokenCredentialsProvider
200

201
Provides credentials by obtaining session tokens for temporary access with MFA.
202

203
```java { .api }
204
public class StsGetSessionTokenCredentialsProvider extends StsCredentialsProvider
205
    implements ToCopyableBuilder<StsGetSessionTokenCredentialsProvider.Builder, StsGetSessionTokenCredentialsProvider> {
206
    
207
    public static Builder builder();
208
    
209
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsGetSessionTokenCredentialsProvider> {
210
        Builder refreshRequest(GetSessionTokenRequest getSessionTokenRequest);
211
        Builder refreshRequest(Consumer<GetSessionTokenRequest.Builder> getSessionTokenRequest);
212
        StsGetSessionTokenCredentialsProvider build();
213
    }
214
}
215
```
216

217
#### Usage Example with MFA
218

219
```java
220
StsGetSessionTokenCredentialsProvider credentialsProvider = 
221
    StsGetSessionTokenCredentialsProvider.builder()
222
        .refreshRequest(GetSessionTokenRequest.builder()
223
            .durationSeconds(3600)
224
            .serialNumber("arn:aws:iam::123456789012:mfa/user")
225
            .tokenCode("123456")
226
            .build())
227
        .build();
228

229
AwsCredentials credentials = credentialsProvider.resolveCredentials();
230
```
231

232
## Helper Classes
233

234
### SessionCredentialsHolder
235

236
Container for credentials with session information.
237

238
```java { .api }
239
public class SessionCredentialsHolder {
240
    public AwsSessionCredentials sessionCredentials();
241
    public Instant sessionCredentialExpiration();
242
    public boolean stale(Duration staleTime);
243
    public boolean needsRefresh(Duration prefetchTime);
244
}
245
```
246

247
## Integration with AWS SDK
248

249
All credential providers implement `AwsCredentialsProvider` and can be used with any AWS service client:
250

251
```java
252
S3Client s3Client = S3Client.builder()
253
    .credentialsProvider(credentialsProvider)
254
    .region(Region.US_EAST_1)
255
    .build();
256
```
257

258
## Environment Variables
259

260
The credential providers respect these environment variables:
261

262
- **AWS_WEB_IDENTITY_TOKEN_FILE**: Path to web identity token file
263
- **AWS_ROLE_ARN**: ARN of the role to assume
264
- **AWS_ROLE_SESSION_NAME**: Session name for role assumption
265

266
## Best Practices
267

268
### Resource Management
269

270
Always close credential providers when done:
271

272
```java
273
try (StsAssumeRoleCredentialsProvider provider = 
274
         StsAssumeRoleCredentialsProvider.builder()
275
             .refreshRequest(request)
276
             .build()) {
277
    
278
    AwsCredentials credentials = provider.resolveCredentials();
279
    // Use credentials
280
}
281
```
282

283
### Async Credential Updates
284

285
Enable asynchronous credential refresh for better performance:
286

287
```java
288
StsAssumeRoleCredentialsProvider provider = 
289
    StsAssumeRoleCredentialsProvider.builder()
290
        .refreshRequest(request)
291
        .asyncCredentialUpdateEnabled(true)
292
        .build();
293
```
294

295
### Custom Timing Configuration
296

297
Configure stale and prefetch times based on your application needs:
298

299
```java
300
StsAssumeRoleCredentialsProvider provider = 
301
    StsAssumeRoleCredentialsProvider.builder()
302
        .refreshRequest(request)
303
        .staleTime(Duration.ofMinutes(5))        // Consider stale after 5 minutes
304
        .prefetchTime(Duration.ofMinutes(15))    // Start refresh 15 minutes before expiry
305
        .build();
306
```
307

308
### Error Handling
309

310
Credential providers throw `StsException` and its subclasses:
311

312
```java
313
try {
314
    AwsCredentials credentials = provider.resolveCredentials();
315
} catch (ExpiredTokenException e) {
316
    // Handle expired token
317
} catch (StsException e) {
318
    // Handle other STS errors
319
}
320
```