0
# Role Assumption Operations
1

2
Core functionality for assuming IAM roles to obtain temporary credentials. This includes basic role assumption, SAML federation, web identity federation, with support for session policies, MFA requirements, and cross-account access.
3

4
## Capabilities
5

6
### Basic Role Assumption
7

8
Assumes an IAM role and returns temporary security credentials for cross-account access or privilege escalation.
9

10
```java { .api }
11
/**
12
 * Returns temporary security credentials for role assumption
13
 * @param assumeRoleRequest Request containing role ARN and session configuration
14
 * @return Result containing temporary credentials and assumed role user information
15
 * @throws MalformedPolicyDocumentException If session policy is malformed
16
 * @throws PackedPolicyTooLargeException If session policies exceed size limits
17
 * @throws RegionDisabledException If STS not activated in requested region
18
 * @throws ExpiredTokenException If current credentials are expired
19
 */
20
AssumeRoleResult assumeRole(AssumeRoleRequest assumeRoleRequest);
21
```
22

23
**Request and Result Types:**
24

25
```java { .api }
26
public class AssumeRoleRequest extends AmazonWebServiceRequest {
27
    public AssumeRoleRequest();
28
    
29
    // Required parameters
30
    public String getRoleArn();
31
    public void setRoleArn(String roleArn);
32
    public AssumeRoleRequest withRoleArn(String roleArn);
33
    
34
    public String getRoleSessionName();
35
    public void setRoleSessionName(String roleSessionName);
36
    public AssumeRoleRequest withRoleSessionName(String roleSessionName);
37
    
38
    // Optional parameters
39
    public Integer getDurationSeconds();
40
    public void setDurationSeconds(Integer durationSeconds);
41
    public AssumeRoleRequest withDurationSeconds(Integer durationSeconds);
42
    
43
    public String getExternalId();
44
    public void setExternalId(String externalId);
45
    public AssumeRoleRequest withExternalId(String externalId);
46
    
47
    public String getPolicy();
48
    public void setPolicy(String policy);
49
    public AssumeRoleRequest withPolicy(String policy);
50
    
51
    public List<PolicyDescriptorType> getPolicyArns();
52
    public void setPolicyArns(List<PolicyDescriptorType> policyArns);
53
    public AssumeRoleRequest withPolicyArns(PolicyDescriptorType... policyArns);
54
    
55
    public String getSerialNumber();
56
    public void setSerialNumber(String serialNumber);
57
    public AssumeRoleRequest withSerialNumber(String serialNumber);
58
    
59
    public String getTokenCode();
60
    public void setTokenCode(String tokenCode);
61
    public AssumeRoleRequest withTokenCode(String tokenCode);
62
    
63
    public String getSourceIdentity();
64
    public void setSourceIdentity(String sourceIdentity);
65
    public AssumeRoleRequest withSourceIdentity(String sourceIdentity);
66
    
67
    public List<Tag> getTags();
68
    public void setTags(List<Tag> tags);
69
    public AssumeRoleRequest withTags(Tag... tags);
70
    
71
    public List<String> getTransitiveTagKeys();
72
    public void setTransitiveTagKeys(List<String> transitiveTagKeys);
73
    public AssumeRoleRequest withTransitiveTagKeys(String... transitiveTagKeys);
74
    
75
    public List<ProvidedContext> getProvidedContexts();
76
    public void setProvidedContexts(List<ProvidedContext> providedContexts);
77
    public AssumeRoleRequest withProvidedContexts(ProvidedContext... providedContexts);
78
}
79

80
public class AssumeRoleResult {
81
    public Credentials getCredentials();
82
    public void setCredentials(Credentials credentials);
83
    
84
    public AssumedRoleUser getAssumedRoleUser();
85
    public void setAssumedRoleUser(AssumedRoleUser assumedRoleUser);
86
    
87
    public Integer getPackedPolicySize();
88
    public void setPackedPolicySize(Integer packedPolicySize);
89
    
90
    public String getSourceIdentity();
91
    public void setSourceIdentity(String sourceIdentity);
92
}
93
```
94

95
**Usage Examples:**
96

97
```java
98
import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
99
import com.amazonaws.services.securitytoken.model.*;
100

101
// Basic role assumption
102
AssumeRoleRequest request = new AssumeRoleRequest()
103
    .withRoleArn("arn:aws:iam::123456789012:role/CrossAccountRole")
104
    .withRoleSessionName("MyApplicationSession")
105
    .withDurationSeconds(3600);
106

107
AssumeRoleResult result = stsClient.assumeRole(request);
108
Credentials credentials = result.getCredentials();
109

110
// Role assumption with session policy
111
String sessionPolicy = "{"
112
    + "\"Version\": \"2012-10-17\","
113
    + "\"Statement\": [{"
114
    + "\"Effect\": \"Allow\","
115
    + "\"Action\": \"s3:GetObject\","
116
    + "\"Resource\": \"arn:aws:s3:::my-bucket/*\""
117
    + "}]}";
118

119
AssumeRoleRequest restrictedRequest = new AssumeRoleRequest()
120
    .withRoleArn("arn:aws:iam::123456789012:role/S3AccessRole")
121
    .withRoleSessionName("RestrictedS3Session")
122
    .withPolicy(sessionPolicy)
123
    .withDurationSeconds(1800);
124

125
AssumeRoleResult restrictedResult = stsClient.assumeRole(restrictedRequest);
126

127
// Role assumption with MFA
128
AssumeRoleRequest mfaRequest = new AssumeRoleRequest()
129
    .withRoleArn("arn:aws:iam::123456789012:role/MFARequiredRole")
130
    .withRoleSessionName("MFASession")
131
    .withSerialNumber("arn:aws:iam::123456789012:mfa/user")
132
    .withTokenCode("123456");
133

134
AssumeRoleResult mfaResult = stsClient.assumeRole(mfaRequest);
135
```
136

137
### SAML Federation Role Assumption
138

139
Returns temporary credentials for users authenticated via SAML identity providers.
140

141
```java { .api }
142
/**
143
 * Returns temporary security credentials for SAML authenticated users
144
 * @param assumeRoleWithSAMLRequest Request containing SAML assertion and role information
145
 * @return Result containing temporary credentials and SAML assertion details
146
 * @throws MalformedPolicyDocumentException If session policy is malformed
147
 * @throws PackedPolicyTooLargeException If session policies exceed size limits
148
 * @throws IDPRejectedClaimException If identity provider rejects the claim
149
 * @throws InvalidIdentityTokenException If SAML assertion is invalid
150
 * @throws ExpiredTokenException If SAML assertion is expired
151
 * @throws RegionDisabledException If STS not activated in requested region
152
 */
153
AssumeRoleWithSAMLResult assumeRoleWithSAML(AssumeRoleWithSAMLRequest assumeRoleWithSAMLRequest);
154
```
155

156
**Request and Result Types:**
157

158
```java { .api }
159
public class AssumeRoleWithSAMLRequest extends AmazonWebServiceRequest {
160
    public AssumeRoleWithSAMLRequest();
161
    
162
    // Required parameters
163
    public String getRoleArn();
164
    public void setRoleArn(String roleArn);
165
    public AssumeRoleWithSAMLRequest withRoleArn(String roleArn);
166
    
167
    public String getPrincipalArn();
168
    public void setPrincipalArn(String principalArn);
169
    public AssumeRoleWithSAMLRequest withPrincipalArn(String principalArn);
170
    
171
    public String getSAMLAssertion();
172
    public void setSAMLAssertion(String samlAssertion);
173
    public AssumeRoleWithSAMLRequest withSAMLAssertion(String samlAssertion);
174
    
175
    // Optional parameters
176
    public List<PolicyDescriptorType> getPolicyArns();
177
    public void setPolicyArns(List<PolicyDescriptorType> policyArns);
178
    public AssumeRoleWithSAMLRequest withPolicyArns(PolicyDescriptorType... policyArns);
179
    
180
    public String getPolicy();
181
    public void setPolicy(String policy);
182
    public AssumeRoleWithSAMLRequest withPolicy(String policy);
183
    
184
    public Integer getDurationSeconds();
185
    public void setDurationSeconds(Integer durationSeconds);
186
    public AssumeRoleWithSAMLRequest withDurationSeconds(Integer durationSeconds);
187
}
188

189
public class AssumeRoleWithSAMLResult {
190
    public Credentials getCredentials();
191
    public void setCredentials(Credentials credentials);
192
    
193
    public AssumedRoleUser getAssumedRoleUser();
194
    public void setAssumedRoleUser(AssumedRoleUser assumedRoleUser);
195
    
196
    public Integer getPackedPolicySize();
197
    public void setPackedPolicySize(Integer packedPolicySize);
198
    
199
    public String getSubject();
200
    public void setSubject(String subject);
201
    
202
    public String getSubjectType();
203
    public void setSubjectType(String subjectType);
204
    
205
    public String getIssuer();
206
    public void setIssuer(String issuer);
207
    
208
    public String getAudience();
209
    public void setAudience(String audience);
210
    
211
    public String getNameQualifier();
212
    public void setNameQualifier(String nameQualifier);
213
    
214
    public String getSourceIdentity();
215
    public void setSourceIdentity(String sourceIdentity);
216
}
217
```
218

219
**Usage Examples:**
220

221
```java
222
// SAML role assumption
223
String base64SAMLAssertion = "PHNhbWw6QXNzZXJ0aW9uIC4uLg=="; // Base64 encoded SAML assertion
224

225
AssumeRoleWithSAMLRequest samlRequest = new AssumeRoleWithSAMLRequest()
226
    .withRoleArn("arn:aws:iam::123456789012:role/SAMLRole")
227
    .withPrincipalArn("arn:aws:iam::123456789012:saml-provider/ExampleProvider")
228
    .withSAMLAssertion(base64SAMLAssertion)
229
    .withDurationSeconds(3600);
230

231
AssumeRoleWithSAMLResult samlResult = stsClient.assumeRoleWithSAML(samlRequest);
232
Credentials samlCredentials = samlResult.getCredentials();
233

234
System.out.println("SAML Subject: " + samlResult.getSubject());
235
System.out.println("Issuer: " + samlResult.getIssuer());
236
```
237

238
### Web Identity Federation Role Assumption
239

240
Returns temporary credentials for users authenticated via web identity providers like Amazon Cognito, Login with Amazon, Facebook, Google, or OpenID Connect.
241

242
```java { .api }
243
/**
244
 * Returns temporary security credentials for web identity authenticated users
245
 * @param assumeRoleWithWebIdentityRequest Request containing web identity token and role information
246
 * @return Result containing temporary credentials and web identity details
247
 * @throws MalformedPolicyDocumentException If session policy is malformed
248
 * @throws PackedPolicyTooLargeException If session policies exceed size limits
249
 * @throws IDPRejectedClaimException If identity provider rejects the claim
250
 * @throws IDPCommunicationErrorException If unable to communicate with identity provider
251
 * @throws InvalidIdentityTokenException If web identity token is invalid
252
 * @throws ExpiredTokenException If web identity token is expired
253
 * @throws RegionDisabledException If STS not activated in requested region
254
 */
255
AssumeRoleWithWebIdentityResult assumeRoleWithWebIdentity(AssumeRoleWithWebIdentityRequest assumeRoleWithWebIdentityRequest);
256
```
257

258
**Request and Result Types:**
259

260
```java { .api }
261
public class AssumeRoleWithWebIdentityRequest extends AmazonWebServiceRequest {
262
    public AssumeRoleWithWebIdentityRequest();
263
    
264
    // Required parameters
265
    public String getRoleArn();
266
    public void setRoleArn(String roleArn);
267
    public AssumeRoleWithWebIdentityRequest withRoleArn(String roleArn);
268
    
269
    public String getRoleSessionName();
270
    public void setRoleSessionName(String roleSessionName);
271
    public AssumeRoleWithWebIdentityRequest withRoleSessionName(String roleSessionName);
272
    
273
    public String getWebIdentityToken();
274
    public void setWebIdentityToken(String webIdentityToken);
275
    public AssumeRoleWithWebIdentityRequest withWebIdentityToken(String webIdentityToken);
276
    
277
    // Optional parameters
278
    public String getProviderId();
279
    public void setProviderId(String providerId);
280
    public AssumeRoleWithWebIdentityRequest withProviderId(String providerId);
281
    
282
    public List<PolicyDescriptorType> getPolicyArns();
283
    public void setPolicyArns(List<PolicyDescriptorType> policyArns);
284
    public AssumeRoleWithWebIdentityRequest withPolicyArns(PolicyDescriptorType... policyArns);
285
    
286
    public String getPolicy();
287
    public void setPolicy(String policy);
288
    public AssumeRoleWithWebIdentityRequest withPolicy(String policy);
289
    
290
    public Integer getDurationSeconds();
291
    public void setDurationSeconds(Integer durationSeconds);
292
    public AssumeRoleWithWebIdentityRequest withDurationSeconds(Integer durationSeconds);
293
}
294

295
public class AssumeRoleWithWebIdentityResult {
296
    public Credentials getCredentials();
297
    public void setCredentials(Credentials credentials);
298
    
299
    public String getSubjectFromWebIdentityToken();
300
    public void setSubjectFromWebIdentityToken(String subjectFromWebIdentityToken);
301
    
302
    public AssumedRoleUser getAssumedRoleUser();
303
    public void setAssumedRoleUser(AssumedRoleUser assumedRoleUser);
304
    
305
    public Integer getPackedPolicySize();
306
    public void setPackedPolicySize(Integer packedPolicySize);
307
    
308
    public String getProvider();
309
    public void setProvider(String provider);
310
    
311
    public String getAudience();
312
    public void setAudience(String audience);
313
    
314
    public String getSourceIdentity();
315
    public void setSourceIdentity(String sourceIdentity);
316
}
317
```
318

319
**Usage Examples:**
320

321
```java
322
// Web identity role assumption with Amazon Cognito
323
String cognitoIdentityToken = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."; // JWT token from Cognito
324

325
AssumeRoleWithWebIdentityRequest webIdRequest = new AssumeRoleWithWebIdentityRequest()
326
    .withRoleArn("arn:aws:iam::123456789012:role/CognitoRole")
327
    .withRoleSessionName("CognitoUserSession")
328
    .withWebIdentityToken(cognitoIdentityToken)
329
    .withProviderId("cognito-identity.amazonaws.com")
330
    .withDurationSeconds(3600);
331

332
AssumeRoleWithWebIdentityResult webIdResult = stsClient.assumeRoleWithWebIdentity(webIdRequest);
333
Credentials webIdCredentials = webIdResult.getCredentials();
334

335
System.out.println("Subject: " + webIdResult.getSubjectFromWebIdentityToken());
336
System.out.println("Provider: " + webIdResult.getProvider());
337

338
// Web identity with Facebook
339
String facebookToken = "EAABwzLixnjYBAO..."; // Facebook access token
340

341
AssumeRoleWithWebIdentityRequest facebookRequest = new AssumeRoleWithWebIdentityRequest()
342
    .withRoleArn("arn:aws:iam::123456789012:role/FacebookRole")
343
    .withRoleSessionName("FacebookUserSession")
344
    .withWebIdentityToken(facebookToken)
345
    .withProviderId("graph.facebook.com");
346

347
AssumeRoleWithWebIdentityResult facebookResult = stsClient.assumeRoleWithWebIdentity(facebookRequest);
348
```
349

350
## Supporting Types
351

352
```java { .api }
353
public class ProvidedContext {
354
    public String getProviderArn();
355
    public void setProviderArn(String providerArn);
356
    
357
    public String getContextAssertion();
358
    public void setContextAssertion(String contextAssertion);
359
}
360
```