0
# AWS Security Token Service (STS) SDK
1

2
The AWS Java SDK for AWS STS provides comprehensive client libraries for communicating with Amazon Web Services Security Token Service. This service enables applications to request temporary, limited-privilege credentials for users, supporting various authentication mechanisms including role assumption, SAML federation, web identity federation, and multi-factor authentication.
3

4
## Package Information
5

6
- **Package Name**: aws-java-sdk-sts
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Group ID**: com.amazonaws
10
- **Artifact ID**: aws-java-sdk-sts
11
- **Version**: 1.12.789
12
- **Installation**: 
13
  ```xml
14
  <dependency>
15
    <groupId>com.amazonaws</groupId>
16
    <artifactId>aws-java-sdk-sts</artifactId>
17
    <version>1.12.789</version>
18
  </dependency>
19
  ```
20

21
## Core Imports
22

23
```java
24
import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
25
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClientBuilder;
26
import com.amazonaws.services.securitytoken.model.*;
27
```
28

29
For asynchronous operations:
30

31
```java
32
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceAsync;
33
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceAsyncClientBuilder;
34
```
35

36
## Basic Usage
37

38
```java
39
import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
40
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClientBuilder;
41
import com.amazonaws.services.securitytoken.model.*;
42

43
// Create STS client
44
AWSSecurityTokenService stsClient = AWSSecurityTokenServiceClientBuilder
45
    .standard()
46
    .withRegion("us-east-1")
47
    .build();
48

49
// Get caller identity
50
GetCallerIdentityResult identity = stsClient.getCallerIdentity(new GetCallerIdentityRequest());
51
System.out.println("Account: " + identity.getAccount());
52
System.out.println("User ARN: " + identity.getArn());
53

54
// Assume a role
55
AssumeRoleRequest assumeRequest = new AssumeRoleRequest()
56
    .withRoleArn("arn:aws:iam::123456789012:role/MyRole")
57
    .withRoleSessionName("MySession")
58
    .withDurationSeconds(3600);
59

60
AssumeRoleResult assumeResult = stsClient.assumeRole(assumeRequest);
61
Credentials credentials = assumeResult.getCredentials();
62

63
System.out.println("Access Key: " + credentials.getAccessKeyId());
64
System.out.println("Secret Key: " + credentials.getSecretAccessKey());
65
System.out.println("Session Token: " + credentials.getSessionToken());
66
```
67

68
## Architecture
69

70
The AWS STS SDK is built around several key components:
71

72
- **Service Interface**: `AWSSecurityTokenService` defines all STS operations with synchronous execution
73
- **Async Interface**: `AWSSecurityTokenServiceAsync` provides asynchronous versions of all operations
74
- **Client Implementations**: Thread-safe clients (`AWSSecurityTokenServiceClient`, `AWSSecurityTokenServiceAsyncClient`) that handle HTTP communication
75
- **Builder Pattern**: Fluent builders for configuring clients with regions, credentials, and custom settings
76
- **Request/Result Objects**: Strongly-typed classes for all API operations with builder patterns
77
- **Model Classes**: Data transfer objects representing AWS STS entities (credentials, users, policies)
78
- **Exception Hierarchy**: Specific exception types for different error conditions
79

80
## Capabilities
81

82
### Client Management
83

84
Core client creation, configuration, and lifecycle management functionality including builders, endpoint configuration, and resource cleanup.
85

86
```java { .api }
87
// Client builders
88
public static AWSSecurityTokenServiceClientBuilder standard();
89
public static AWSSecurityTokenService defaultClient();
90
public static AWSSecurityTokenServiceAsyncClientBuilder standard();
91
public static AWSSecurityTokenServiceAsync defaultClient();
92

93
// Client interface
94
public interface AWSSecurityTokenService {
95
    void setEndpoint(String endpoint);
96
    void setRegion(Region region);
97
    void shutdown();
98
    ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request);
99
}
100
```
101

102
[Client Management](./client-management.md)
103

104
### Role Assumption Operations
105

106
Core functionality for assuming IAM roles to obtain temporary credentials, including cross-account access, session policies, and MFA requirements.
107

108
```java { .api }
109
AssumeRoleResult assumeRole(AssumeRoleRequest assumeRoleRequest);
110
AssumeRoleWithSAMLResult assumeRoleWithSAML(AssumeRoleWithSAMLRequest assumeRoleWithSAMLRequest);
111
AssumeRoleWithWebIdentityResult assumeRoleWithWebIdentity(AssumeRoleWithWebIdentityRequest assumeRoleWithWebIdentityRequest);
112
```
113

114
[Role Assumption](./role-assumption.md)
115

116
### Federation Operations
117

118
Federation functionality for obtaining temporary credentials through external identity providers and custom federation brokers.
119

120
```java { .api }
121
GetFederationTokenResult getFederationToken(GetFederationTokenRequest getFederationTokenRequest);
122
```
123

124
[Federation](./federation.md)
125

126
### Session Token Operations
127

128
Session token management for MFA-protected operations and temporary credential generation for existing IAM users.
129

130
```java { .api }
131
GetSessionTokenResult getSessionToken(GetSessionTokenRequest getSessionTokenRequest);
132
GetSessionTokenResult getSessionToken();
133
```
134

135
[Session Tokens](./session-tokens.md)
136

137
### Utility Operations
138

139
Utility operations for debugging authorization failures, retrieving caller identity, and determining account ownership of access keys.
140

141
```java { .api }
142
GetCallerIdentityResult getCallerIdentity(GetCallerIdentityRequest getCallerIdentityRequest);
143
GetAccessKeyInfoResult getAccessKeyInfo(GetAccessKeyInfoRequest getAccessKeyInfoRequest);
144
DecodeAuthorizationMessageResult decodeAuthorizationMessage(DecodeAuthorizationMessageRequest decodeAuthorizationMessageRequest);
145
```
146

147
[Utilities](./utilities.md)
148

149
## Core Types
150

151
```java { .api }
152
public class Credentials {
153
    public Credentials();
154
    public Credentials(String accessKeyId, String secretAccessKey, String sessionToken, Date expiration);
155
    public String getAccessKeyId();
156
    public String getSecretAccessKey(); 
157
    public String getSessionToken();
158
    public Date getExpiration();
159
    public void setAccessKeyId(String accessKeyId);
160
    public void setSecretAccessKey(String secretAccessKey);
161
    public void setSessionToken(String sessionToken);
162
    public void setExpiration(Date expiration);
163
}
164

165
public class AssumedRoleUser {
166
    public String getAssumedRoleId();
167
    public String getArn();
168
    public void setAssumedRoleId(String assumedRoleId);
169
    public void setArn(String arn);
170
}
171

172
public class FederatedUser {
173
    public String getFederatedUserId();
174
    public String getArn();
175
    public void setFederatedUserId(String federatedUserId);
176
    public void setArn(String arn);
177
}
178

179
public class Tag {
180
    public String getKey();
181
    public String getValue();
182
    public void setKey(String key);
183
    public void setValue(String value);
184
}
185

186
public class PolicyDescriptorType {
187
    public String getArn();
188
    public void setArn(String arn);
189
}
190
```
191

192
## Exception Handling
193

194
```java { .api }
195
// Base exception
196
public class AWSSecurityTokenServiceException extends AmazonServiceException { }
197

198
// Specific exceptions
199
public class ExpiredTokenException extends AWSSecurityTokenServiceException { }
200
public class InvalidIdentityTokenException extends AWSSecurityTokenServiceException { }
201
public class MalformedPolicyDocumentException extends AWSSecurityTokenServiceException { }
202
public class PackedPolicyTooLargeException extends AWSSecurityTokenServiceException { }
203
public class RegionDisabledException extends AWSSecurityTokenServiceException { }
204
public class IDPRejectedClaimException extends AWSSecurityTokenServiceException { }
205
public class IDPCommunicationErrorException extends AWSSecurityTokenServiceException { }
206
public class InvalidAuthorizationMessageException extends AWSSecurityTokenServiceException { }
207
```