0
# STS Client Operations
1

2
The STS Client provides direct access to all AWS Security Token Service operations. Each operation returns temporary security credentials or identity information through type-safe request/response objects.
3

4
## Core Imports
5

6
```java
7
import software.amazon.awssdk.services.sts.StsClient;
8
import software.amazon.awssdk.services.sts.model.*;
9
import software.amazon.awssdk.core.SdkClient;
10
import software.amazon.awssdk.regions.Region;
11
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
12
import java.net.URI;
13
import java.time.Instant;
14
import java.util.List;
15
```
16

17
## Client Creation
18

19
```java { .api }
20
public interface StsClient extends SdkClient {
21
    static StsClientBuilder builder();
22
}
23

24
public interface StsClientBuilder {
25
    StsClientBuilder region(Region region);
26
    StsClientBuilder credentialsProvider(AwsCredentialsProvider credentialsProvider);
27
    StsClientBuilder endpointOverride(URI endpointOverride);
28
    StsClient build();
29
}
30
```
31

32
### Basic Client Setup
33

34
```java
35
StsClient stsClient = StsClient.builder()
36
    .region(Region.US_EAST_1)
37
    .build();
38
```
39

40
## Core Operations
41

42
### AssumeRole
43

44
Returns temporary security credentials for cross-account access or privilege escalation.
45

46
```java { .api }
47
AssumeRoleResponse assumeRole(AssumeRoleRequest request);
48

49
public interface AssumeRoleRequest {
50
    static AssumeRoleRequestBuilder builder();
51
    String roleArn();
52
    String roleSessionName();
53
    Integer durationSeconds();
54
    String policy();
55
    List<PolicyDescriptorType> policyArns();
56
    String externalId();
57
    String serialNumber();
58
    String tokenCode();
59
    List<Tag> tags();
60
    List<String> transitiveTagKeys();
61
    String sourceIdentity();
62
}
63

64
public interface AssumeRoleResponse {
65
    Credentials credentials();
66
    AssumedRoleUser assumedRoleUser();
67
    Integer packedPolicySize();
68
    String sourceIdentity();
69
}
70
```
71

72
#### Usage Example
73

74
```java
75
AssumeRoleRequest request = AssumeRoleRequest.builder()
76
    .roleArn("arn:aws:iam::123456789012:role/MyRole")
77
    .roleSessionName("MySessionName")
78
    .durationSeconds(3600)
79
    .policy("{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":\"s3:GetObject\",\"Resource\":\"*\"}]}")
80
    .build();
81

82
AssumeRoleResponse response = stsClient.assumeRole(request);
83
Credentials credentials = response.credentials();
84
```
85

86
### AssumeRoleWithWebIdentity
87

88
Returns temporary credentials for users authenticated with web identity providers (OAuth, OpenID Connect).
89

90
```java { .api }
91
AssumeRoleWithWebIdentityResponse assumeRoleWithWebIdentity(AssumeRoleWithWebIdentityRequest request);
92

93
public interface AssumeRoleWithWebIdentityRequest {
94
    static AssumeRoleWithWebIdentityRequestBuilder builder();
95
    String roleArn();
96
    String roleSessionName();
97
    String webIdentityToken();
98
    String providerId();
99
    String policy();
100
    List<PolicyDescriptorType> policyArns();
101
    Integer durationSeconds();
102
}
103

104
public interface AssumeRoleWithWebIdentityResponse {
105
    Credentials credentials();
106
    String subjectFromWebIdentityToken();
107
    AssumedRoleUser assumedRoleUser();
108
    Integer packedPolicySize();
109
    String provider();
110
    String audience();
111
    String sourceIdentity();
112
}
113
```
114

115
### AssumeRoot
116

117
Returns temporary credentials for privileged tasks on member accounts in your organization. Requires centralized root access to be enabled.
118

119
```java { .api }
120
AssumeRootResponse assumeRoot(AssumeRootRequest request);
121

122
public interface AssumeRootRequest {
123
    static AssumeRootRequestBuilder builder();
124
    String targetPrincipal();
125
    PolicyDescriptorType taskPolicyArn();
126
    Integer durationSeconds();
127
}
128

129
public interface AssumeRootResponse {
130
    Credentials credentials();
131
    String sourceIdentity();
132
}
133
```
134

135
#### Usage Example
136

137
```java
138
AssumeRootRequest request = AssumeRootRequest.builder()
139
    .targetPrincipal("123456789012")  // Member account ID
140
    .taskPolicyArn(PolicyDescriptorType.builder()
141
        .arn("arn:aws:iam::aws:policy/IAMAuditRootUserCredentials")
142
        .build())
143
    .durationSeconds(3600)
144
    .build();
145

146
AssumeRootResponse response = stsClient.assumeRoot(request);
147
Credentials credentials = response.credentials();
148
```
149

150
### AssumeRoleWithSAML
151

152
Returns temporary credentials for users authenticated via SAML.
153

154
```java { .api }
155
AssumeRoleWithSAMLResponse assumeRoleWithSAML(AssumeRoleWithSAMLRequest request);
156

157
public interface AssumeRoleWithSAMLRequest {
158
    static AssumeRoleWithSAMLRequestBuilder builder();
159
    String roleArn();
160
    String principalArn();
161
    String samlAssertion();
162
    String policy();
163
    List<PolicyDescriptorType> policyArns();
164
    Integer durationSeconds();
165
}
166

167
public interface AssumeRoleWithSAMLResponse {
168
    Credentials credentials();
169
    AssumedRoleUser assumedRoleUser();
170
    Integer packedPolicySize();
171
    String subject();
172
    String subjectType();
173
    String issuer();
174
    String audience();
175
    String nameQualifier();
176
    String sourceIdentity();
177
}
178
```
179

180
### GetCallerIdentity
181

182
Returns information about the identity whose credentials are used to call the operation.
183

184
```java { .api }
185
GetCallerIdentityResponse getCallerIdentity(GetCallerIdentityRequest request);
186

187
public interface GetCallerIdentityRequest {
188
    static GetCallerIdentityRequestBuilder builder();
189
}
190

191
public interface GetCallerIdentityResponse {
192
    String userId();
193
    String account(); 
194
    String arn();
195
}
196
```
197

198
#### Usage Example
199

200
```java
201
GetCallerIdentityResponse response = stsClient.getCallerIdentity(
202
    GetCallerIdentityRequest.builder().build()
203
);
204

205
System.out.println("User ID: " + response.userId());
206
System.out.println("Account: " + response.account());
207
System.out.println("ARN: " + response.arn());
208
```
209

210
### GetSessionToken
211

212
Returns temporary credentials for AWS account root or IAM users.
213

214
```java { .api }
215
GetSessionTokenResponse getSessionToken(GetSessionTokenRequest request);
216

217
public interface GetSessionTokenRequest {
218
    static GetSessionTokenRequestBuilder builder();
219
    Integer durationSeconds();
220
    String serialNumber();
221
    String tokenCode();
222
}
223

224
public interface GetSessionTokenResponse {
225
    Credentials credentials();
226
}
227
```
228

229
### GetFederationToken
230

231
Returns temporary credentials for federated users.
232

233
```java { .api }
234
GetFederationTokenResponse getFederationToken(GetFederationTokenRequest request);
235

236
public interface GetFederationTokenRequest {
237
    static GetFederationTokenRequestBuilder builder();
238
    String name();
239
    String policy();
240
    List<PolicyDescriptorType> policyArns();
241
    Integer durationSeconds();
242
    List<Tag> tags();
243
}
244

245
public interface GetFederationTokenResponse {
246
    Credentials credentials();
247
    FederatedUser federatedUser();
248
    Integer packedPolicySize();
249
}
250
```
251

252
### GetAccessKeyInfo
253

254
Returns the account identifier for the specified access key ID.
255

256
```java { .api }
257
GetAccessKeyInfoResponse getAccessKeyInfo(GetAccessKeyInfoRequest request);
258

259
public interface GetAccessKeyInfoRequest {
260
    static GetAccessKeyInfoRequestBuilder builder();
261
    String accessKeyId();
262
}
263

264
public interface GetAccessKeyInfoResponse {
265
    String account();
266
}
267
```
268

269
### DecodeAuthorizationMessage
270

271
Decodes additional information about the authorization status of requests.
272

273
```java { .api }
274
DecodeAuthorizationMessageResponse decodeAuthorizationMessage(DecodeAuthorizationMessageRequest request);
275

276
public interface DecodeAuthorizationMessageRequest {
277
    static DecodeAuthorizationMessageRequestBuilder builder();
278
    String encodedMessage();
279
}
280

281
public interface DecodeAuthorizationMessageResponse {
282
    String decodedMessage();
283
}
284
```
285

286
## Common Types
287

288
### Credentials
289

290
```java { .api }
291
public interface Credentials {
292
    String accessKeyId();
293
    String secretAccessKey();
294
    String sessionToken();
295
    Instant expiration();
296
}
297
```
298

299
### AssumedRoleUser
300

301
```java { .api }
302
public interface AssumedRoleUser {
303
    String assumedRoleId();
304
    String arn();
305
}
306
```
307

308
### FederatedUser
309

310
```java { .api }
311
public interface FederatedUser {
312
    String federatedUserId();
313
    String arn();
314
}
315
```
316

317
### PolicyDescriptorType
318

319
```java { .api }
320
public interface PolicyDescriptorType {
321
    static PolicyDescriptorTypeBuilder builder();
322
    String arn();
323
}
324
```
325

326
### Tag
327

328
```java { .api }
329
public interface Tag {
330
    static TagBuilder builder();
331
    String key();
332
    String value();
333
}
334
```
335

336
## Exception Handling
337

338
All STS operations can throw the following exceptions:
339

340
```java { .api }
341
public class ExpiredTokenException extends StsException {
342
    // The web identity token that was passed is expired or is not valid
343
}
344

345
public class IdpCommunicationErrorException extends StsException {
346
    // The identity provider (IdP) reported that authentication failed
347
}
348

349
public class IdpRejectedClaimException extends StsException {
350
    // The identity provider (IdP) reported that authentication failed
351
}
352

353
public class InvalidAuthorizationMessageException extends StsException {
354
    // The error returned if the message passed to DecodeAuthorizationMessage was invalid
355
}
356

357
public class InvalidIdentityTokenException extends StsException {
358
    // The web identity token that was passed could not be validated by AWS
359
}
360

361
public class MalformedPolicyDocumentException extends StsException {
362
    // The request was rejected because the policy document was malformed
363
}
364

365
public class PackedPolicyTooLargeException extends StsException {
366
    // The request was rejected because the total packed size of the session policies and policy ARNs exceeded the limit
367
}
368

369
public class RegionDisabledException extends StsException {
370
    // STS is not activated in the requested region for the account
371
}
372
```
373

374
## Error Handling Example
375

376
```java
377
try {
378
    AssumeRoleResponse response = stsClient.assumeRole(request);
379
    // Process successful response
380
} catch (ExpiredTokenException e) {
381
    // Handle expired token
382
    System.err.println("Token expired: " + e.getMessage());
383
} catch (MalformedPolicyDocumentException e) {
384
    // Handle policy document error
385
    System.err.println("Invalid policy: " + e.getMessage());
386
} catch (IdpCommunicationErrorException e) {
387
    // Handle identity provider communication error
388
    System.err.println("IdP communication error: " + e.getMessage());
389
} catch (StsException e) {
390
    // Handle other STS errors
391
    System.err.println("STS error: " + e.getMessage());
392
}
393
```