0
# AWS STS Java SDK
1

2
The AWS STS (Security Token Service) Java SDK provides comprehensive client classes for communicating with AWS Security Token Service. It enables Java applications to obtain temporary AWS credentials through various authentication mechanisms including role assumption, web identity token authentication, SAML-based authentication, and federation tokens. The SDK includes both low-level client operations and high-level credential providers with built-in session management and automatic credential refresh capabilities.
3

4
## Package Information
5

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

21
## Core Imports
22

23
```java
24
import software.amazon.awssdk.services.sts.StsClient;
25
import software.amazon.awssdk.services.sts.model.*;
26
import software.amazon.awssdk.services.sts.auth.*;
27
import software.amazon.awssdk.auth.credentials.AwsCredentials;
28
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
29
import software.amazon.awssdk.regions.Region;
30
```
31

32
## Basic Usage
33

34
### Using STS Client Directly
35

36
```java
37
import software.amazon.awssdk.services.sts.StsClient;
38
import software.amazon.awssdk.services.sts.model.*;
39

40
// Create STS client
41
StsClient stsClient = StsClient.builder()
42
    .region(Region.US_EAST_1)
43
    .build();
44

45
// Assume a role
46
AssumeRoleRequest request = AssumeRoleRequest.builder()
47
    .roleArn("arn:aws:iam::123456789012:role/MyRole")
48
    .roleSessionName("MySession")
49
    .durationSeconds(3600)
50
    .build();
51

52
AssumeRoleResponse response = stsClient.assumeRole(request);
53
Credentials credentials = response.credentials();
54

55
System.out.println("Access Key: " + credentials.accessKeyId());
56
System.out.println("Secret Key: " + credentials.secretAccessKey());
57
System.out.println("Session Token: " + credentials.sessionToken());
58
```
59

60
### Using Credential Providers
61

62
```java
63
import software.amazon.awssdk.services.sts.auth.StsAssumeRoleCredentialsProvider;
64
import software.amazon.awssdk.auth.credentials.AwsCredentials;
65

66
// Create credential provider
67
StsAssumeRoleCredentialsProvider credentialsProvider = 
68
    StsAssumeRoleCredentialsProvider.builder()
69
        .refreshRequest(AssumeRoleRequest.builder()
70
            .roleArn("arn:aws:iam::123456789012:role/MyRole")
71
            .roleSessionName("MySession")
72
            .build())
73
        .build();
74

75
// Get credentials (automatically cached and refreshed)
76
AwsCredentials credentials = credentialsProvider.resolveCredentials();
77
```
78

79
## Architecture
80

81
The AWS STS Java SDK is organized around several key components:
82

83
- **STS Client API**: Low-level client interface providing direct access to all STS operations
84
- **Credential Providers**: High-level abstractions that automatically manage credential lifecycle
85
- **Model Classes**: Type-safe request/response objects and data models for all STS operations
86
- **Authentication**: Integration with AWS credential provider chains and profile systems
87
- **Caching**: Built-in credential caching with configurable refresh behavior
88

89
## Capabilities
90

91
### STS Client Operations
92

93
Direct access to all AWS STS operations for temporary credential management, caller identity verification, and authorization message decoding.
94

95
```java { .api }
96
public interface StsClient extends SdkClient {
97
    AssumeRoleResponse assumeRole(AssumeRoleRequest request);
98
    AssumeRoleWithSAMLResponse assumeRoleWithSAML(AssumeRoleWithSAMLRequest request);
99
    AssumeRoleWithWebIdentityResponse assumeRoleWithWebIdentity(AssumeRoleWithWebIdentityRequest request);
100
    AssumeRootResponse assumeRoot(AssumeRootRequest request);
101
    DecodeAuthorizationMessageResponse decodeAuthorizationMessage(DecodeAuthorizationMessageRequest request);
102
    GetAccessKeyInfoResponse getAccessKeyInfo(GetAccessKeyInfoRequest request);
103
    GetCallerIdentityResponse getCallerIdentity(GetCallerIdentityRequest request);
104
    GetFederationTokenResponse getFederationToken(GetFederationTokenRequest request);
105
    GetSessionTokenResponse getSessionToken(GetSessionTokenRequest request);
106
    
107
    static StsClientBuilder builder();
108
}
109
```
110

111
[STS Client Operations](./client-operations.md)
112

113
### Credential Providers
114

115
High-level credential providers that automatically handle credential acquisition, caching, and refresh using various STS operations. Integrates seamlessly with AWS SDK credential provider chains.
116

117
```java { .api }
118
public abstract class StsCredentialsProvider implements AwsCredentialsProvider {
119
    public abstract AwsCredentials resolveCredentials();
120
    public Duration staleTime();
121
    public Duration prefetchTime();
122
}
123

124
public class StsAssumeRoleCredentialsProvider extends StsCredentialsProvider {
125
    public static Builder builder();
126
}
127

128
public class StsAssumeRoleWithWebIdentityCredentialsProvider extends StsCredentialsProvider {
129
    public static Builder builder();
130
}
131
```
132

133
[Credential Providers](./credential-providers.md)
134

135
## Types
136

137
### Core Data Models
138

139
```java { .api }
140
public interface Credentials {
141
    String accessKeyId();
142
    String secretAccessKey();
143
    String sessionToken();
144
    Instant expiration();
145
}
146

147
public interface AssumedRoleUser {
148
    String assumedRoleId();
149
    String arn();
150
}
151

152
public interface FederatedUser {
153
    String federatedUserId();
154
    String arn();
155
}
156

157
public interface Tag {
158
    String key();
159
    String value();
160
}
161
```
162

163
### Common Exceptions
164

165
```java { .api }
166
public class ExpiredTokenException extends StsException {
167
    // Token has expired
168
}
169

170
public class IdpCommunicationErrorException extends StsException {
171
    // Identity provider communication error
172
}
173

174
public class IdpRejectedClaimException extends StsException {
175
    // Identity provider rejected claim
176
}
177

178
public class InvalidAuthorizationMessageException extends StsException {
179
    // Invalid authorization message
180
}
181

182
public class InvalidIdentityTokenException extends StsException {
183
    // Invalid identity token provided
184
}
185

186
public class MalformedPolicyDocumentException extends StsException {
187
    // Policy document is malformed
188
}
189

190
public class PackedPolicyTooLargeException extends StsException {
191
    // Policy size exceeded limit
192
}
193

194
public class RegionDisabledException extends StsException {
195
    // STS is not activated in the requested region
196
}
197
```