0
# AWS SDK for Java v2 - Auth Module
1

2
The AWS SDK for Java v2 Auth module provides comprehensive authentication and signing capabilities for AWS services. It includes credential management, request signing, and token-based authentication support for Java applications.
3

4
## Package Information
5

6
- **Package Name**: auth
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: software.amazon.awssdk
10
- **Artifact ID**: auth
11
- **Version**: 2.32.31
12
- **Installation**: 
13
  ```xml
14
  <dependency>
15
    <groupId>software.amazon.awssdk</groupId>
16
    <artifactId>auth</artifactId>
17
    <version>2.32.31</version>
18
  </dependency>
19
  ```
20

21
## Core Imports
22

23
```java
24
// Credential interfaces and implementations
25
import software.amazon.awssdk.auth.credentials.AwsCredentials;
26
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
27
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
28
import software.amazon.awssdk.auth.credentials.AwsSessionCredentials;
29

30
// Common credential providers
31
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
32
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
33
import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider;
34
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
35

36
// Token-based authentication
37
import software.amazon.awssdk.auth.token.credentials.SdkToken;
38
import software.amazon.awssdk.auth.token.credentials.SdkTokenProvider;
39
import software.amazon.awssdk.auth.token.credentials.DefaultAwsTokenProvider;
40

41
// Utility classes
42
import software.amazon.awssdk.auth.credentials.CredentialUtils;
43
import software.amazon.awssdk.auth.token.credentials.TokenUtils;
44
```
45

46
Wildcard imports (use when importing multiple classes):
47

48
```java
49
import software.amazon.awssdk.auth.credentials.*;
50
import software.amazon.awssdk.auth.token.credentials.*;
51
```
52

53
## Basic Usage
54

55
```java
56
import software.amazon.awssdk.auth.credentials.*;
57
import software.amazon.awssdk.auth.token.credentials.*;
58
import java.time.Instant;
59

60
// Use default credential provider chain (recommended)
61
AwsCredentialsProvider credentialsProvider = DefaultCredentialsProvider.builder()
62
    .asyncCredentialUpdateEnabled(true)
63
    .build();
64
AwsCredentials credentials = credentialsProvider.resolveCredentials();
65
System.out.println("Access Key ID: " + credentials.accessKeyId());
66

67
// Use static credentials for testing/development
68
AwsCredentials staticCredentials = AwsBasicCredentials.builder()
69
    .accessKeyId("ACCESS_KEY")
70
    .secretAccessKey("SECRET_KEY")
71
    .providerName("MyStaticProvider")
72
    .build();
73
AwsCredentialsProvider staticProvider = StaticCredentialsProvider.create(staticCredentials);
74

75
// Use session credentials with token and expiration
76
AwsSessionCredentials sessionCredentials = AwsSessionCredentials.builder()
77
    .accessKeyId("TEMP_ACCESS_KEY")
78
    .secretAccessKey("TEMP_SECRET_KEY")
79
    .sessionToken("SESSION_TOKEN")
80
    .expirationTime(Instant.now().plusSeconds(3600)) // 1 hour expiration
81
    .providerName("AssumeRoleProvider")
82
    .build();
83

84
// Create custom provider chain with specific ordering
85
AwsCredentialsProvider customChain = AwsCredentialsProviderChain.builder()
86
    .addCredentialsProvider(EnvironmentVariableCredentialsProvider.create())
87
    .addCredentialsProvider(ProfileCredentialsProvider.create("my-profile"))
88
    .addCredentialsProvider(InstanceProfileCredentialsProvider.create())
89
    .build();
90

91
// Token-based authentication (for SSO)
92
SdkTokenProvider tokenProvider = DefaultAwsTokenProvider.builder()
93
    .asyncTokenUpdateEnabled(true)
94
    .build();
95
SdkToken token = tokenProvider.resolveToken();
96

97
// Check credential anonymity
98
boolean isAnonymous = CredentialUtils.isAnonymous(credentials);
99
if (!isAnonymous) {
100
    System.out.println("Using authenticated credentials");
101
}
102

103
// Always close resources when done
104
credentialsProvider.close();
105
tokenProvider.close();
106
```
107

108
## Architecture
109

110
The AWS Auth module is organized around several key components:
111

112
- **Credential Types**: Core credential interfaces and implementations (`AwsCredentials`, `AwsBasicCredentials`, `AwsSessionCredentials`)
113
- **Credential Providers**: Various sources for loading credentials with automatic fallback chains
114
- **Request Signers**: AWS4 signature implementations for authenticating requests (mostly deprecated)
115
- **Token Authentication**: OAuth/Bearer token support for modern authentication flows
116
- **Builder Pattern**: Fluent APIs with immutable configurations and extensive customization options
117
- **Chain of Responsibility**: Multiple credential sources with automatic fallback behavior
118

119
## Capabilities
120

121
### Credential Management
122

123
Core credential types and comprehensive provider ecosystem for loading AWS credentials from various sources including environment, profiles, containers, and instance metadata.
124

125
```java { .api }
126
interface AwsCredentials extends AwsCredentialsIdentity {
127
    String accessKeyId();
128
    String secretAccessKey();
129
}
130

131
interface AwsCredentialsProvider extends IdentityProvider<AwsCredentialsIdentity> {
132
    AwsCredentials resolveCredentials();
133
}
134

135
class AwsBasicCredentials implements AwsCredentials {
136
    static AwsBasicCredentials create(String accessKeyId, String secretAccessKey);
137
    static Builder builder();
138
}
139

140
class AwsSessionCredentials implements AwsCredentials, AwsSessionCredentialsIdentity {
141
    static AwsSessionCredentials create(String accessKey, String secretKey, String sessionToken);
142
    String sessionToken();
143
    Optional<Instant> expirationTime();
144
}
145
```
146

147
[Credential Management](./credential-management.md)
148

149
### Credential Providers
150

151
Built-in providers for loading credentials from environment variables, system properties, AWS profiles, EC2 instance metadata, container metadata, and custom provider chains.
152

153
```java { .api }
154
class DefaultCredentialsProvider implements AwsCredentialsProvider {
155
    static DefaultCredentialsProvider create();
156
    static Builder builder();
157
}
158

159
class AwsCredentialsProviderChain implements AwsCredentialsProvider {
160
    static Builder builder();
161
    static AwsCredentialsProviderChain of(AwsCredentialsProvider... providers);
162
}
163

164
class StaticCredentialsProvider implements AwsCredentialsProvider {
165
    static StaticCredentialsProvider create(AwsCredentials credentials);
166
}
167

168
class EnvironmentVariableCredentialsProvider implements AwsCredentialsProvider {
169
    static EnvironmentVariableCredentialsProvider create();
170
}
171
```
172

173
[Credential Providers](./credential-providers.md)
174

175
### Token-Based Authentication
176

177
OAuth and Bearer token authentication support for modern AWS services requiring token-based authentication flows.
178

179
```java { .api }
180
interface SdkToken extends TokenIdentity {
181
    String token();
182
    Optional<Instant> expirationTime();
183
}
184

185
interface SdkTokenProvider extends IdentityProvider<TokenIdentity> {
186
    SdkToken resolveToken();
187
}
188

189
class StaticTokenProvider implements SdkTokenProvider {
190
    static StaticTokenProvider create(SdkToken token);
191
}
192

193
class DefaultAwsTokenProvider implements SdkTokenProvider {
194
    static DefaultAwsTokenProvider create();
195
    static Builder builder();
196
}
197
```
198

199
[Token Authentication](./token-authentication.md)
200

201
### Request Signing (Legacy)
202

203
**Note**: The signer classes in this module are deprecated in favor of the new `http-auth-aws` module.
204

205
Legacy AWS Signature Version 4 implementations for request signing, including specialized signers for S3 and event streams.
206

207
```java { .api }
208
// DEPRECATED - Use AwsV4HttpSigner from 'http-auth-aws' module
209
class Aws4Signer implements Signer {
210
    static Aws4Signer create();
211
}
212

213
// DEPRECATED - Use AwsV4HttpSigner from 'http-auth-aws' module  
214
class AsyncAws4Signer implements AsyncSigner {
215
    static AsyncAws4Signer create();
216
}
217

218
// DEPRECATED - Use BearerHttpSigner from 'http-auth' module
219
class BearerTokenSigner implements Signer {
220
    static BearerTokenSigner create();
221
}
222
```
223

224
[Request Signing (Legacy)](./request-signing.md)
225

226
## Types
227

228
```java { .api }
229
interface ToCopyableBuilder<B, T> {
230
    B toBuilder();
231
}
232

233
interface SdkAutoCloseable extends AutoCloseable {
234
    void close();
235
}
236

237
class ExecutionAttribute<T> {
238
    // Execution context attributes for signers
239
}
240

241
enum RegionScope {
242
    GLOBAL, REGIONAL
243
}
244
```