CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-amazonaws--aws-java-sdk-sts

Java client library for Amazon Web Services Security Token Service (AWS STS) enabling temporary security credentials and federated user access

—

Pending
Overview
Eval results
Files

role-assumption.mddocs/

Role Assumption Operations

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.

Capabilities

Basic Role Assumption

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

/**
 * Returns temporary security credentials for role assumption
 * @param assumeRoleRequest Request containing role ARN and session configuration
 * @return Result containing temporary credentials and assumed role user information
 * @throws MalformedPolicyDocumentException If session policy is malformed
 * @throws PackedPolicyTooLargeException If session policies exceed size limits
 * @throws RegionDisabledException If STS not activated in requested region
 * @throws ExpiredTokenException If current credentials are expired
 */
AssumeRoleResult assumeRole(AssumeRoleRequest assumeRoleRequest);

Request and Result Types:

public class AssumeRoleRequest extends AmazonWebServiceRequest {
    public AssumeRoleRequest();
    
    // Required parameters
    public String getRoleArn();
    public void setRoleArn(String roleArn);
    public AssumeRoleRequest withRoleArn(String roleArn);
    
    public String getRoleSessionName();
    public void setRoleSessionName(String roleSessionName);
    public AssumeRoleRequest withRoleSessionName(String roleSessionName);
    
    // Optional parameters
    public Integer getDurationSeconds();
    public void setDurationSeconds(Integer durationSeconds);
    public AssumeRoleRequest withDurationSeconds(Integer durationSeconds);
    
    public String getExternalId();
    public void setExternalId(String externalId);
    public AssumeRoleRequest withExternalId(String externalId);
    
    public String getPolicy();
    public void setPolicy(String policy);
    public AssumeRoleRequest withPolicy(String policy);
    
    public List<PolicyDescriptorType> getPolicyArns();
    public void setPolicyArns(List<PolicyDescriptorType> policyArns);
    public AssumeRoleRequest withPolicyArns(PolicyDescriptorType... policyArns);
    
    public String getSerialNumber();
    public void setSerialNumber(String serialNumber);
    public AssumeRoleRequest withSerialNumber(String serialNumber);
    
    public String getTokenCode();
    public void setTokenCode(String tokenCode);
    public AssumeRoleRequest withTokenCode(String tokenCode);
    
    public String getSourceIdentity();
    public void setSourceIdentity(String sourceIdentity);
    public AssumeRoleRequest withSourceIdentity(String sourceIdentity);
    
    public List<Tag> getTags();
    public void setTags(List<Tag> tags);
    public AssumeRoleRequest withTags(Tag... tags);
    
    public List<String> getTransitiveTagKeys();
    public void setTransitiveTagKeys(List<String> transitiveTagKeys);
    public AssumeRoleRequest withTransitiveTagKeys(String... transitiveTagKeys);
    
    public List<ProvidedContext> getProvidedContexts();
    public void setProvidedContexts(List<ProvidedContext> providedContexts);
    public AssumeRoleRequest withProvidedContexts(ProvidedContext... providedContexts);
}

public class AssumeRoleResult {
    public Credentials getCredentials();
    public void setCredentials(Credentials credentials);
    
    public AssumedRoleUser getAssumedRoleUser();
    public void setAssumedRoleUser(AssumedRoleUser assumedRoleUser);
    
    public Integer getPackedPolicySize();
    public void setPackedPolicySize(Integer packedPolicySize);
    
    public String getSourceIdentity();
    public void setSourceIdentity(String sourceIdentity);
}

Usage Examples:

import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
import com.amazonaws.services.securitytoken.model.*;

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

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

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

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

AssumeRoleResult restrictedResult = stsClient.assumeRole(restrictedRequest);

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

AssumeRoleResult mfaResult = stsClient.assumeRole(mfaRequest);

SAML Federation Role Assumption

Returns temporary credentials for users authenticated via SAML identity providers.

/**
 * Returns temporary security credentials for SAML authenticated users
 * @param assumeRoleWithSAMLRequest Request containing SAML assertion and role information
 * @return Result containing temporary credentials and SAML assertion details
 * @throws MalformedPolicyDocumentException If session policy is malformed
 * @throws PackedPolicyTooLargeException If session policies exceed size limits
 * @throws IDPRejectedClaimException If identity provider rejects the claim
 * @throws InvalidIdentityTokenException If SAML assertion is invalid
 * @throws ExpiredTokenException If SAML assertion is expired
 * @throws RegionDisabledException If STS not activated in requested region
 */
AssumeRoleWithSAMLResult assumeRoleWithSAML(AssumeRoleWithSAMLRequest assumeRoleWithSAMLRequest);

Request and Result Types:

public class AssumeRoleWithSAMLRequest extends AmazonWebServiceRequest {
    public AssumeRoleWithSAMLRequest();
    
    // Required parameters
    public String getRoleArn();
    public void setRoleArn(String roleArn);
    public AssumeRoleWithSAMLRequest withRoleArn(String roleArn);
    
    public String getPrincipalArn();
    public void setPrincipalArn(String principalArn);
    public AssumeRoleWithSAMLRequest withPrincipalArn(String principalArn);
    
    public String getSAMLAssertion();
    public void setSAMLAssertion(String samlAssertion);
    public AssumeRoleWithSAMLRequest withSAMLAssertion(String samlAssertion);
    
    // Optional parameters
    public List<PolicyDescriptorType> getPolicyArns();
    public void setPolicyArns(List<PolicyDescriptorType> policyArns);
    public AssumeRoleWithSAMLRequest withPolicyArns(PolicyDescriptorType... policyArns);
    
    public String getPolicy();
    public void setPolicy(String policy);
    public AssumeRoleWithSAMLRequest withPolicy(String policy);
    
    public Integer getDurationSeconds();
    public void setDurationSeconds(Integer durationSeconds);
    public AssumeRoleWithSAMLRequest withDurationSeconds(Integer durationSeconds);
}

public class AssumeRoleWithSAMLResult {
    public Credentials getCredentials();
    public void setCredentials(Credentials credentials);
    
    public AssumedRoleUser getAssumedRoleUser();
    public void setAssumedRoleUser(AssumedRoleUser assumedRoleUser);
    
    public Integer getPackedPolicySize();
    public void setPackedPolicySize(Integer packedPolicySize);
    
    public String getSubject();
    public void setSubject(String subject);
    
    public String getSubjectType();
    public void setSubjectType(String subjectType);
    
    public String getIssuer();
    public void setIssuer(String issuer);
    
    public String getAudience();
    public void setAudience(String audience);
    
    public String getNameQualifier();
    public void setNameQualifier(String nameQualifier);
    
    public String getSourceIdentity();
    public void setSourceIdentity(String sourceIdentity);
}

Usage Examples:

// SAML role assumption
String base64SAMLAssertion = "PHNhbWw6QXNzZXJ0aW9uIC4uLg=="; // Base64 encoded SAML assertion

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

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

System.out.println("SAML Subject: " + samlResult.getSubject());
System.out.println("Issuer: " + samlResult.getIssuer());

Web Identity Federation Role Assumption

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

/**
 * Returns temporary security credentials for web identity authenticated users
 * @param assumeRoleWithWebIdentityRequest Request containing web identity token and role information
 * @return Result containing temporary credentials and web identity details
 * @throws MalformedPolicyDocumentException If session policy is malformed
 * @throws PackedPolicyTooLargeException If session policies exceed size limits
 * @throws IDPRejectedClaimException If identity provider rejects the claim
 * @throws IDPCommunicationErrorException If unable to communicate with identity provider
 * @throws InvalidIdentityTokenException If web identity token is invalid
 * @throws ExpiredTokenException If web identity token is expired
 * @throws RegionDisabledException If STS not activated in requested region
 */
AssumeRoleWithWebIdentityResult assumeRoleWithWebIdentity(AssumeRoleWithWebIdentityRequest assumeRoleWithWebIdentityRequest);

Request and Result Types:

public class AssumeRoleWithWebIdentityRequest extends AmazonWebServiceRequest {
    public AssumeRoleWithWebIdentityRequest();
    
    // Required parameters
    public String getRoleArn();
    public void setRoleArn(String roleArn);
    public AssumeRoleWithWebIdentityRequest withRoleArn(String roleArn);
    
    public String getRoleSessionName();
    public void setRoleSessionName(String roleSessionName);
    public AssumeRoleWithWebIdentityRequest withRoleSessionName(String roleSessionName);
    
    public String getWebIdentityToken();
    public void setWebIdentityToken(String webIdentityToken);
    public AssumeRoleWithWebIdentityRequest withWebIdentityToken(String webIdentityToken);
    
    // Optional parameters
    public String getProviderId();
    public void setProviderId(String providerId);
    public AssumeRoleWithWebIdentityRequest withProviderId(String providerId);
    
    public List<PolicyDescriptorType> getPolicyArns();
    public void setPolicyArns(List<PolicyDescriptorType> policyArns);
    public AssumeRoleWithWebIdentityRequest withPolicyArns(PolicyDescriptorType... policyArns);
    
    public String getPolicy();
    public void setPolicy(String policy);
    public AssumeRoleWithWebIdentityRequest withPolicy(String policy);
    
    public Integer getDurationSeconds();
    public void setDurationSeconds(Integer durationSeconds);
    public AssumeRoleWithWebIdentityRequest withDurationSeconds(Integer durationSeconds);
}

public class AssumeRoleWithWebIdentityResult {
    public Credentials getCredentials();
    public void setCredentials(Credentials credentials);
    
    public String getSubjectFromWebIdentityToken();
    public void setSubjectFromWebIdentityToken(String subjectFromWebIdentityToken);
    
    public AssumedRoleUser getAssumedRoleUser();
    public void setAssumedRoleUser(AssumedRoleUser assumedRoleUser);
    
    public Integer getPackedPolicySize();
    public void setPackedPolicySize(Integer packedPolicySize);
    
    public String getProvider();
    public void setProvider(String provider);
    
    public String getAudience();
    public void setAudience(String audience);
    
    public String getSourceIdentity();
    public void setSourceIdentity(String sourceIdentity);
}

Usage Examples:

// Web identity role assumption with Amazon Cognito
String cognitoIdentityToken = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."; // JWT token from Cognito

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

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

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

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

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

AssumeRoleWithWebIdentityResult facebookResult = stsClient.assumeRoleWithWebIdentity(facebookRequest);

Supporting Types

public class ProvidedContext {
    public String getProviderArn();
    public void setProviderArn(String providerArn);
    
    public String getContextAssertion();
    public void setContextAssertion(String contextAssertion);
}

Install with Tessl CLI

npx tessl i tessl/maven-com-amazonaws--aws-java-sdk-sts

docs

client-management.md

federation.md

index.md

role-assumption.md

session-tokens.md

utilities.md

tile.json