0
# Credential Management
1

2
Core credential types providing secure AWS authentication through immutable credential objects with builder pattern support and optional metadata.
3

4
## Capabilities
5

6
### AwsCredentials Interface
7

8
Base interface for AWS authentication credentials providing access to access key and secret access key.
9

10
```java { .api }
11
/**
12
 * Base interface for AWS credentials providing access to AWS access key and secret key
13
 * Extends AwsCredentialsIdentity for compatibility with identity framework
14
 */
15
interface AwsCredentials extends AwsCredentialsIdentity {
16
    String accessKeyId();
17
    String secretAccessKey();
18
    Optional<String> providerName();
19
    Optional<String> accountId();
20
}
21
```
22

23
### AwsBasicCredentials Class
24

25
Immutable implementation of basic AWS credentials containing access key and secret access key.
26

27
```java { .api }
28
/**
29
 * Basic implementation of AWS credentials with access key and secret key
30
 * Immutable class with builder pattern support
31
 */
32
final class AwsBasicCredentials implements AwsCredentials, ToCopyableBuilder<Builder, AwsBasicCredentials> {
33
    /**
34
     * Create basic credentials from access key and secret key
35
     * @param accessKeyId AWS access key ID
36
     * @param secretAccessKey AWS secret access key
37
     * @return new AwsBasicCredentials instance
38
     */
39
    static AwsBasicCredentials create(String accessKeyId, String secretAccessKey);
40
    
41
    /**
42
     * Create builder for custom configuration
43
     * @return Builder instance
44
     */
45
    static Builder builder();
46
    
47
    String accessKeyId();
48
    String secretAccessKey();
49
    Optional<String> providerName();
50
    Optional<String> accountId();
51
    Builder toBuilder();
52
    
53
    interface Builder extends CopyableBuilder<Builder, AwsBasicCredentials> {
54
        Builder accessKeyId(String accessKeyId);
55
        Builder secretAccessKey(String secretAccessKey);
56
        Builder providerName(String providerName);
57
        Builder accountId(String accountId);
58
        AwsBasicCredentials build();
59
    }
60
}
61
```
62

63
**Usage Examples:**
64

65
```java
66
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
67

68
// Create basic credentials
69
AwsBasicCredentials credentials = AwsBasicCredentials.create(
70
    "AKIAIOSFODNN7EXAMPLE", 
71
    "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
72
);
73

74
// Using builder for additional metadata
75
AwsBasicCredentials credentialsWithMetadata = AwsBasicCredentials.builder()
76
    .accessKeyId("AKIAIOSFODNN7EXAMPLE")
77
    .secretAccessKey("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")
78
    .providerName("MyCustomProvider")
79
    .accountId("123456789012")
80
    .build();
81

82
// Create modified copy using builder
83
AwsBasicCredentials updatedCredentials = credentials.toBuilder()
84
    .providerName("UpdatedProvider")
85
    .build();
86
```
87

88
### AwsSessionCredentials Class
89

90
AWS credentials with session token for temporary access, commonly used with AWS STS (Security Token Service).
91

92
```java { .api }
93
/**
94
 * AWS credentials with session token for temporary access
95
 * Extends AwsCredentials and AwsSessionCredentialsIdentity
96
 */
97
final class AwsSessionCredentials implements AwsCredentials, AwsSessionCredentialsIdentity, 
98
                                           ToCopyableBuilder<Builder, AwsSessionCredentials> {
99
    /**
100
     * Create session credentials with access key, secret key, and session token
101
     * @param accessKey AWS access key ID
102
     * @param secretKey AWS secret access key  
103
     * @param sessionToken AWS session token
104
     * @return new AwsSessionCredentials instance
105
     */
106
    static AwsSessionCredentials create(String accessKey, String secretKey, String sessionToken);
107
    
108
    /**
109
     * Create builder for custom configuration including expiration time
110
     * @return Builder instance
111
     */
112
    static Builder builder();
113
    
114
    String accessKeyId();
115
    String secretAccessKey();
116
    String sessionToken();
117
    Optional<Instant> expirationTime();
118
    Optional<String> providerName();
119
    Optional<String> accountId();
120
    Builder toBuilder();
121
    
122
    interface Builder extends CopyableBuilder<Builder, AwsSessionCredentials> {
123
        Builder accessKeyId(String accessKeyId);
124
        Builder secretAccessKey(String secretAccessKey);
125
        Builder sessionToken(String sessionToken);
126
        Builder expirationTime(Instant expirationTime);
127
        Builder providerName(String providerName);
128
        Builder accountId(String accountId);
129
        AwsSessionCredentials build();
130
    }
131
}
132
```
133

134
**Usage Examples:**
135

136
```java
137
import software.amazon.awssdk.auth.credentials.AwsSessionCredentials;
138
import java.time.Instant;
139

140
// Create session credentials from STS response
141
AwsSessionCredentials sessionCredentials = AwsSessionCredentials.create(
142
    "AKIAIOSFODNN7EXAMPLE",
143
    "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
144
    "AQoDYXdzEJr...<remainder of security token>"
145
);
146

147
// Using builder with expiration time
148
AwsSessionCredentials credentialsWithExpiry = AwsSessionCredentials.builder()
149
    .accessKeyId("AKIAIOSFODNN7EXAMPLE")
150
    .secretAccessKey("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")
151
    .sessionToken("AQoDYXdzEJr...<remainder of security token>")
152
    .expirationTime(Instant.now().plusSeconds(3600)) // 1 hour from now
153
    .providerName("STSCredentialsProvider")
154
    .accountId("123456789012")
155
    .build();
156

157
// Check if credentials are expired
158
if (credentialsWithExpiry.expirationTime().isPresent()) {
159
    Instant expiry = credentialsWithExpiry.expirationTime().get();
160
    if (expiry.isBefore(Instant.now())) {
161
        // Credentials are expired, need to refresh
162
    }
163
}
164
```
165

166
### AwsCredentialsProvider Interface
167

168
Functional interface for loading AWS credentials with support for both synchronous and asynchronous resolution.
169

170
```java { .api }
171
/**
172
 * Functional interface for loading AWS credentials
173
 * Supports both sync and async credential resolution
174
 */
175
@FunctionalInterface
176
interface AwsCredentialsProvider extends IdentityProvider<AwsCredentialsIdentity> {
177
    /**
178
     * Resolve credentials synchronously
179
     * @return AwsCredentials instance
180
     * @throws SdkClientException if credentials cannot be resolved
181
     */
182
    AwsCredentials resolveCredentials();
183
    
184
    /**
185
     * Return the identity type this provider handles  
186
     * @return Class representing AwsCredentialsIdentity
187
     */
188
    default Class<AwsCredentialsIdentity> identityType() {
189
        return AwsCredentialsIdentity.class;
190
    }
191
    
192
    /**
193
     * Resolve credentials asynchronously
194
     * @param request resolve identity request
195
     * @return CompletableFuture with resolved identity
196
     */
197
    default CompletableFuture<AwsCredentialsIdentity> resolveIdentity(ResolveIdentityRequest request) {
198
        return CompletableFuture.supplyAsync(() -> resolveCredentials());
199
    }
200
}
201
```
202

203
**Usage Examples:**
204

205
```java
206
import software.amazon.awssdk.auth.credentials.*;
207

208
// Create custom credential provider
209
AwsCredentialsProvider customProvider = () -> {
210
    // Custom logic to retrieve credentials
211
    return AwsBasicCredentials.create("key", "secret");
212
};
213

214
// Use provider to resolve credentials
215
AwsCredentials credentials = customProvider.resolveCredentials();
216

217
// Async resolution
218
CompletableFuture<AwsCredentialsIdentity> futureCredentials = 
219
    customProvider.resolveIdentity(ResolveIdentityRequest.builder().build());
220
```
221

222
## Error Handling
223

224
Credential resolution may throw the following exceptions:
225

226
- **SdkClientException**: When credentials cannot be resolved from any source
227
- **IllegalArgumentException**: When invalid parameters are provided to builders
228
- **SecurityException**: When access to credential sources is denied
229

230
```java
231
try {
232
    AwsCredentials credentials = provider.resolveCredentials();
233
} catch (SdkClientException e) {
234
    // Handle credential resolution failure
235
    logger.error("Failed to resolve credentials: " + e.getMessage());
236
}
237
```
238

239
## Utility Classes
240

241
### CredentialUtils Class
242

243
Utility class providing helper methods for working with AWS credentials and credential providers.
244

245
```java { .api }
246
/**
247
 * Utility class for AWS credentials operations
248
 * Provides conversion and validation methods
249
 */
250
final class CredentialUtils {
251
    /**
252
     * Check if credentials are anonymous (null or empty access key)
253
     * @param credentials AWS credentials to check
254
     * @return true if credentials are anonymous, false otherwise
255
     */
256
    static boolean isAnonymous(AwsCredentials credentials);
257
    
258
    /**
259
     * Check if credential identity is anonymous
260
     * @param credentials AWS credentials identity to check  
261
     * @return true if credentials are anonymous, false otherwise
262
     */
263
    static boolean isAnonymous(AwsCredentialsIdentity credentials);
264
    
265
    /**
266
     * Convert AwsCredentialsIdentity to AwsCredentials
267
     * @param awsCredentialsIdentity credentials identity to convert
268
     * @return AwsCredentials instance
269
     */
270
    static AwsCredentials toCredentials(AwsCredentialsIdentity awsCredentialsIdentity);
271
    
272
    /**
273
     * Convert generic identity provider to AWS credentials provider
274
     * @param identityProvider generic identity provider
275
     * @return AwsCredentialsProvider instance
276
     */
277
    static AwsCredentialsProvider toCredentialsProvider(
278
        IdentityProvider<? extends AwsCredentialsIdentity> identityProvider);
279
}
280
```
281

282
**Usage Examples:**
283

284
```java
285
import software.amazon.awssdk.auth.credentials.CredentialUtils;
286

287
// Check if credentials are anonymous
288
AwsCredentials credentials = // ... obtain credentials
289
boolean isAnonymous = CredentialUtils.isAnonymous(credentials);
290
if (isAnonymous) {
291
    System.out.println("Using anonymous credentials");
292
} else {
293
    System.out.println("Using authenticated credentials");
294
}
295

296
// Convert identity to credentials
297
AwsCredentialsIdentity identity = // ... obtain identity
298
AwsCredentials converted = CredentialUtils.toCredentials(identity);
299

300
// Convert identity provider to credentials provider
301
IdentityProvider<AwsCredentialsIdentity> genericProvider = // ... 
302
AwsCredentialsProvider credentialsProvider = 
303
    CredentialUtils.toCredentialsProvider(genericProvider);
304
```
305

306
### Supporting Interfaces
307

308
#### HttpCredentialsProvider Interface
309

310
Base interface for HTTP-based credential providers such as EC2 instance metadata and container metadata providers.
311

312
```java { .api }
313
/**
314
 * Base interface for HTTP-based credential providers
315
 * Extends AwsCredentialsProvider and SdkAutoCloseable for resource management
316
 */
317
interface HttpCredentialsProvider extends AwsCredentialsProvider, SdkAutoCloseable {
318
    // Inherits resolveCredentials() from AwsCredentialsProvider
319
    // Inherits close() from SdkAutoCloseable
320
}
321
```