0
# Authentication & Credentials
1

2
The AWS Java SDK Core provides comprehensive authentication and credential management capabilities, supporting multiple credential sources and automatic credential provider chains.
3

4
## Core Credential Interfaces
5

6
### Basic Credentials
7

8
```java { .api }
9
// Basic AWS credentials interface
10
interface AWSCredentials {
11
    String getAWSAccessKeyId();
12
    String getAWSSecretKey();
13
}
14

15
// Session-based credentials with temporary token
16
interface AWSSessionCredentials extends AWSCredentials {
17
    String getSessionToken();
18
}
19

20
// Refreshable session credentials
21
interface AWSRefreshableSessionCredentials extends AWSSessionCredentials {
22
    void refresh();
23
}
24

25
// Account ID aware credentials
26
interface AccountIdAware {
27
    String getAccountId();
28
}
29

30
// Provider name aware credentials  
31
interface ProviderNameAware {
32
    String getProviderName();
33
}
34
```
35

36
### Basic Credential Implementations
37

38
```java { .api }
39
// Basic access key and secret key credentials
40
class BasicAWSCredentials implements AWSCredentials {
41
    public BasicAWSCredentials(String accessKey, String secretKey);
42
    public String getAWSAccessKeyId();
43
    public String getAWSSecretKey();
44
}
45

46
// Session credentials with temporary token
47
class BasicSessionCredentials extends BasicAWSCredentials 
48
    implements AWSSessionCredentials {
49
    public BasicSessionCredentials(String accessKey, String secretKey, String sessionToken);
50
    public String getSessionToken();
51
}
52

53
// Anonymous credentials (no authentication)
54
class AnonymousAWSCredentials implements AWSCredentials {
55
    public String getAWSAccessKeyId(); // Returns null
56
    public String getAWSSecretKey(); // Returns null
57
}
58

59
// Credentials from properties file
60
class PropertiesCredentials implements AWSCredentials {
61
    public PropertiesCredentials(File file) throws FileNotFoundException, IOException;
62
    public PropertiesCredentials(InputStream inputStream) throws IOException;
63
    public String getAWSAccessKeyId();
64
    public String getAWSSecretKey();
65
}
66
```
67

68
## Credential Providers
69

70
### Core Provider Interface
71

72
```java { .api }
73
// Base credential provider interface
74
interface AWSCredentialsProvider {
75
    AWSCredentials getCredentials();
76
    void refresh();
77
}
78

79
// Session credential provider interface
80
interface AWSSessionCredentialsProvider {
81
    AWSSessionCredentials getCredentials();
82
    void refresh();
83
}
84
```
85

86
### Built-in Credential Providers
87

88
```java { .api }
89
// Static credential provider
90
class AWSStaticCredentialsProvider implements AWSCredentialsProvider {
91
    public AWSStaticCredentialsProvider(AWSCredentials credentials);
92
    public AWSCredentials getCredentials();
93
    public void refresh();
94
}
95

96
// Environment variable provider
97
class EnvironmentVariableCredentialsProvider implements AWSCredentialsProvider {
98
    public AWSCredentials getCredentials();
99
    public void refresh();
100
    public String toString();
101
}
102

103
// System properties provider
104
class SystemPropertiesCredentialsProvider implements AWSCredentialsProvider {
105
    public AWSCredentials getCredentials(); 
106
    public void refresh();
107
    public String toString();
108
}
109

110
// AWS profile provider
111
class ProfileCredentialsProvider implements AWSCredentialsProvider {
112
    public ProfileCredentialsProvider();
113
    public ProfileCredentialsProvider(String profileName);
114
    public ProfileCredentialsProvider(String profilesConfigFilePath, String profileName);
115
    public AWSCredentials getCredentials();
116
    public void refresh();
117
}
118

119
// EC2 instance profile provider
120
class InstanceProfileCredentialsProvider implements AWSCredentialsProvider {
121
    public static InstanceProfileCredentialsProvider getInstance();
122
    public InstanceProfileCredentialsProvider();
123
    public InstanceProfileCredentialsProvider(boolean refreshCredentialsAsync);
124
    public AWSCredentials getCredentials();
125
    public void refresh();
126
}
127

128
// ECS container credentials provider
129
class ContainerCredentialsProvider implements AWSCredentialsProvider {
130
    public ContainerCredentialsProvider();
131
    public ContainerCredentialsProvider(CredentialsEndpointProvider credentialsEndpointProvider);
132
    public AWSCredentials getCredentials();
133
    public void refresh();
134
}
135

136
// EC2/ECS wrapper provider
137
class EC2ContainerCredentialsProviderWrapper implements AWSCredentialsProvider {
138
    public AWSCredentials getCredentials();
139
    public void refresh();
140
}
141

142
// Classpath properties file provider
143
class ClasspathPropertiesFileCredentialsProvider implements AWSCredentialsProvider {
144
    public ClasspathPropertiesFileCredentialsProvider();
145
    public ClasspathPropertiesFileCredentialsProvider(String credentialsFilePath);
146
    public AWSCredentials getCredentials();
147
    public void refresh();
148
}
149

150
// Properties file provider
151
class PropertiesFileCredentialsProvider implements AWSCredentialsProvider {
152
    public PropertiesFileCredentialsProvider(String credentialsFilePath);
153
    public AWSCredentials getCredentials();
154
    public void refresh();
155
}
156

157
// Web identity token provider
158
class WebIdentityTokenCredentialsProvider implements AWSSessionCredentialsProvider {
159
    public static WebIdentityTokenCredentialsProvider create();
160
    public static WebIdentityTokenCredentialsProvider.Builder builder();
161
    public AWSSessionCredentials getCredentials();
162
    public void refresh();
163
}
164
```
165

166
### Default Credential Provider Chain
167

168
```java { .api }
169
// Default credential provider chain
170
class DefaultAWSCredentialsProviderChain extends AWSCredentialsProviderChain {
171
    public static DefaultAWSCredentialsProviderChain getInstance();
172
    public AWSCredentials getCredentials();
173
    public void refresh();
174
}
175

176
// Custom credential provider chain
177
class AWSCredentialsProviderChain implements AWSCredentialsProvider {
178
    public AWSCredentialsProviderChain(AWSCredentialsProvider... credentialsProviders);
179
    public AWSCredentials getCredentials();
180
    public void refresh();
181
    public void setReuseLastProviderEnabled(boolean reuseLastProviderEnabled);
182
}
183
```
184

185
## Usage Examples
186

187
### Basic Authentication Setup
188

189
```java
190
import com.amazonaws.auth.*;
191

192
// Option 1: Use default credential provider chain (recommended)
193
AWSCredentialsProvider credentialsProvider = 
194
    DefaultAWSCredentialsProviderChain.getInstance();
195

196
// Option 2: Static credentials (not recommended for production)
197
AWSCredentials credentials = new BasicAWSCredentials("accessKey", "secretKey");
198
AWSCredentialsProvider staticProvider = new AWSStaticCredentialsProvider(credentials);
199

200
// Option 3: Specific provider
201
AWSCredentialsProvider profileProvider = new ProfileCredentialsProvider("my-profile");
202

203
// Option 4: Custom chain
204
AWSCredentialsProviderChain customChain = new AWSCredentialsProviderChain(
205
    new EnvironmentVariableCredentialsProvider(),
206
    new SystemPropertiesCredentialsProvider(), 
207
    new ProfileCredentialsProvider(),
208
    new InstanceProfileCredentialsProvider()
209
);
210
```
211

212
### Session Credentials
213

214
```java
215
import com.amazonaws.auth.*;
216

217
// Create session credentials with token
218
AWSSessionCredentials sessionCredentials = new BasicSessionCredentials(
219
    "accessKey", "secretKey", "sessionToken"
220
);
221

222
// Web identity token provider (for assume role with web identity)
223
WebIdentityTokenCredentialsProvider webIdentityProvider = 
224
    WebIdentityTokenCredentialsProvider.builder()
225
        .roleArn("arn:aws:iam::123456789012:role/MyRole")
226
        .roleSessionName("MySession")
227
        .webIdentityTokenFile("/path/to/token/file")
228
        .build();
229
```
230

231
### Environment Variables
232

233
The SDK recognizes these environment variables:
234

235
- `AWS_ACCESS_KEY_ID` - AWS access key
236
- `AWS_SECRET_ACCESS_KEY` - AWS secret key  
237
- `AWS_SESSION_TOKEN` - AWS session token (for temporary credentials)
238
- `AWS_PROFILE` - AWS profile name
239
- `AWS_CREDENTIAL_PROFILES_FILE` - Custom credentials file location
240

241
### System Properties  
242

243
The SDK recognizes these system properties:
244

245
- `aws.accessKeyId` - AWS access key
246
- `aws.secretKey` - AWS secret key
247
- `aws.sessionToken` - AWS session token
248

249
## Request Signers
250

251
### Core Signer Interface
252

253
```java { .api }
254
// Base signer interface
255
interface Signer {
256
    void sign(Request<?> request, AWSCredentials credentials);
257
}
258

259
// Presigner interface for generating presigned URLs
260
interface Presigner {
261
    void presignRequest(Request<?> request, AWSCredentials credentials, Date expiration);
262
}
263

264
// Request signer interface
265
interface RequestSigner {
266
    void sign(Request<?> request);
267
}
268
```
269

270
### AWS Signature Implementations
271

272
```java { .api }
273
// AWS Signature Version 4 signer
274
class AWS4Signer implements Signer, RegionAwareSigner, ServiceAwareSigner {
275
    public AWS4Signer();
276
    public AWS4Signer(boolean doubleUrlEncode);
277
    public void setRegionName(String regionName);
278
    public void setServiceName(String serviceName);
279
    public void sign(Request<?> request, AWSCredentials credentials);
280
}
281

282
// AWS SigV4 with unsigned payload
283
class AWS4UnsignedPayloadSigner extends AWS4Signer {
284
    public void sign(Request<?> request, AWSCredentials credentials);
285
}
286

287
// AWS Signature Version 3 signer  
288
class AWS3Signer implements Signer {
289
    public void sign(Request<?> request, AWSCredentials credentials);
290
}
291

292
// Query string signer for URL parameters
293
class QueryStringSigner implements Signer {
294
    public void sign(Request<?> request, AWSCredentials credentials);
295
}
296

297
// No-operation signer (no signing)
298
class NoOpSigner implements Signer {
299
    public void sign(Request<?> request, AWSCredentials credentials);
300
}
301
```
302

303
### Signer Extensions
304

305
```java { .api }
306
// Region-aware signer
307
interface RegionAwareSigner extends Signer {
308
    void setRegionName(String regionName);
309
}
310

311
// Service-aware signer
312
interface ServiceAwareSigner extends Signer {
313
    void setServiceName(String serviceName);
314
}
315

316
// Endpoint prefix aware signer
317
interface EndpointPrefixAwareSigner extends Signer {
318
    void setEndpointPrefix(String endpointPrefix);
319
}
320

321
// Region from endpoint resolver aware signer
322
interface RegionFromEndpointResolverAwareSigner extends Signer {
323
    void setRegionFromEndpointResolver(Region region);
324
}
325

326
// Signer type awareness
327
interface SignerTypeAware {
328
    void setSignerType(String signerType);
329
}
330

331
// Marker for handling null credentials
332
interface CanHandleNullCredentials {
333
    // Marker interface - no methods
334
}
335
```
336

337
### Signer Configuration
338

339
```java { .api }
340
// Signer parameters
341
class SignerParams {
342
    public String getRegionName();
343
    public String getServiceName();
344
    public Date getSigningDate();
345
    public AWSCredentials getCredentials();
346
}
347

348
// Static signer provider
349
class StaticSignerProvider implements RequestSigner {
350
    public StaticSignerProvider(Signer signer);
351
    public void sign(Request<?> request);
352
}
353

354
// Signing algorithms enumeration
355
enum SigningAlgorithm {
356
    HmacSHA1("HmacSHA1"),
357
    HmacSHA256("HmacSHA256");
358
    
359
    public String toString();
360
}
361

362
// Signature versions
363
enum SignatureVersion {
364
    V1, V2, V3, V4
365
}
366

367
// SDK clock interface
368
interface SdkClock {
369
    Date currentDate();
370
}
371
```
372

373
## Policy Framework
374

375
### Core Policy Classes
376

377
```java { .api }
378
// IAM policy representation
379
class Policy {
380
    public Policy();
381
    public Policy(String json);
382
    public String getId();
383
    public Policy withId(String id);
384
    public List<Statement> getStatements();
385
    public Policy withStatements(Statement... statements);
386
    public String toJson();
387
}
388

389
// Policy statement
390
class Statement {
391
    public Statement(Effect effect);
392
    public String getId();
393
    public Statement withId(String id);
394
    public Effect getEffect();
395
    public Statement withEffect(Effect effect);
396
    public List<Principal> getPrincipals();
397
    public Statement withPrincipals(Principal... principals);
398
    public List<Action> getActions();
399
    public Statement withActions(Action... actions);
400
    public List<Resource> getResources();  
401
    public Statement withResources(Resource... resources);
402
    public List<Condition> getConditions();
403
    public Statement withConditions(Condition... conditions);
404
    
405
    enum Effect { Allow, Deny }
406
}
407

408
// Policy principal (user, role, service)
409
class Principal {
410
    public Principal(String provider, String id);
411
    public Principal(Services service);
412
    public String getProvider();
413
    public String getId();
414
    public Services getService();
415
    
416
    enum Services {
417
        AmazonEC2("ec2.amazonaws.com"),
418
        AWSLambda("lambda.amazonaws.com"),
419
        AllUsers("*");
420
        
421
        public String getServiceId();
422
    }
423
}
424

425
// Policy action interface
426
interface Action {
427
    String getActionName();
428
}
429

430
// Policy resource  
431
class Resource {
432
    public Resource(String resource);
433
    public String getResource();
434
}
435

436
// Policy condition
437
class Condition {
438
    public String getType();
439
    public String getConditionKey();
440
    public List<String> getValues();
441
}
442
```
443

444
### Policy Conditions
445

446
```java { .api }
447
// String-based conditions
448
class StringCondition extends Condition {
449
    public static StringCondition StringEquals(String key, String value);
450
    public static StringCondition StringNotEquals(String key, String value);
451
    public static StringCondition StringLike(String key, String value);
452
    public static StringCondition StringNotLike(String key, String value);
453
}
454

455
// Numeric conditions  
456
class NumericCondition extends Condition {
457
    public static NumericCondition NumericEquals(String key, String value);
458
    public static NumericCondition NumericNotEquals(String key, String value);
459
    public static NumericCondition NumericLessThan(String key, String value);
460
    public static NumericCondition NumericLessThanEquals(String key, String value);
461
    public static NumericCondition NumericGreaterThan(String key, String value);
462
    public static NumericCondition NumericGreaterThanEquals(String key, String value);
463
}
464

465
// Date conditions
466
class DateCondition extends Condition {
467
    public static DateCondition DateEquals(String key, Date value);
468
    public static DateCondition DateNotEquals(String key, Date value);  
469
    public static DateCondition DateLessThan(String key, Date value);
470
    public static DateCondition DateLessThanEquals(String key, Date value);
471
    public static DateCondition DateGreaterThan(String key, Date value);
472
    public static DateCondition DateGreaterThanEquals(String key, Date value);
473
}
474

475
// Boolean conditions
476
class BooleanCondition extends Condition {
477
    public static BooleanCondition Bool(String key, boolean value);
478
}
479

480
// IP address conditions
481
class IpAddressCondition extends Condition {
482
    public static IpAddressCondition IpAddress(String key, String ipAddressRange);
483
    public static IpAddressCondition NotIpAddress(String key, String ipAddressRange);
484
}
485

486
// ARN conditions
487
class ArnCondition extends Condition {
488
    public static ArnCondition ArnEquals(String key, String arn);
489
    public static ArnCondition ArnLike(String key, String arn);  
490
    public static ArnCondition ArnNotEquals(String key, String arn);
491
    public static ArnCondition ArnNotLike(String key, String arn);
492
}
493

494
// Condition factory
495
class ConditionFactory {
496
    public static Condition newCondition(String type, String key, String value);
497
    public static StringCondition newStringCondition(StringComparisonType comparisonType, 
498
                                                    String key, String value);
499
    public static NumericCondition newNumericCondition(NumericComparisonType comparisonType,
500
                                                      String key, String value);
501
    public static DateCondition newDateCondition(DateComparisonType comparisonType,
502
                                                String key, Date value);
503
    public static BooleanCondition newBooleanCondition(String key, boolean value);
504
    public static IpAddressCondition newIpAddressCondition(String key, String ipAddressRange);
505
    public static ArnCondition newArnCondition(ArnComparisonType comparisonType,
506
                                              String key, String arn);
507
}
508
```
509

510
## Usage Examples
511

512
### Policy Construction
513

514
```java
515
import com.amazonaws.auth.policy.*;
516

517
// Create a simple policy
518
Policy policy = new Policy()
519
    .withStatements(
520
        new Statement(Statement.Effect.Allow)
521
            .withPrincipals(Principal.AllUsers)
522
            .withActions(new Action() {
523
                public String getActionName() { return "s3:GetObject"; }
524
            })
525
            .withResources(new Resource("arn:aws:s3:::my-bucket/*"))
526
            .withConditions(
527
                StringCondition.StringEquals("aws:Referer", "http://www.example.com/*")
528
            )
529
    );
530

531
String policyJson = policy.toJson();
532
```
533

534
### Custom Credential Provider
535

536
```java
537
import com.amazonaws.auth.*;
538

539
public class CustomCredentialsProvider implements AWSCredentialsProvider {
540
    
541
    @Override
542
    public AWSCredentials getCredentials() {
543
        // Custom logic to obtain credentials
544
        String accessKey = getAccessKeyFromCustomSource();
545
        String secretKey = getSecretKeyFromCustomSource();
546
        return new BasicAWSCredentials(accessKey, secretKey);
547
    }
548
    
549
    @Override
550
    public void refresh() {
551
        // Custom refresh logic
552
    }
553
    
554
    private String getAccessKeyFromCustomSource() {
555
        // Implementation specific to your credential source
556
        return "your-access-key";
557
    }
558
    
559
    private String getSecretKeyFromCustomSource() {
560
        // Implementation specific to your credential source  
561
        return "your-secret-key";
562
    }
563
}
564
```
565

566
## Best Practices
567

568
1. **Use Default Credential Provider Chain**: Always start with `DefaultAWSCredentialsProviderChain.getInstance()` for automatic credential resolution.
569

570
2. **Avoid Hardcoded Credentials**: Never hardcode credentials in source code. Use environment variables, profiles, or IAM roles.
571

572
3. **Use IAM Roles**: For EC2 instances and ECS containers, use IAM roles instead of storing credentials.
573

574
4. **Rotate Credentials**: Regularly rotate access keys and use temporary credentials when possible.
575

576
5. **Secure Credential Files**: Ensure credential files have appropriate file permissions (600).
577

578
6. **Profile Management**: Use named profiles for different environments and applications.
579

580
7. **Session Credentials**: Use session credentials for temporary access and assume role operations.
581

582
The authentication system provides comprehensive support for all AWS credential types and sources, enabling secure and flexible authentication for AWS service operations.