CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-software-amazon-awssdk--sts

AWS Security Token Service (STS) Java SDK providing client classes for temporary credential authentication mechanisms

Overview
Eval results
Files

client-operations.mddocs/

STS Client Operations

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.

Core Imports

import software.amazon.awssdk.services.sts.StsClient;
import software.amazon.awssdk.services.sts.model.*;
import software.amazon.awssdk.core.SdkClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
import java.net.URI;
import java.time.Instant;
import java.util.List;

Client Creation

public interface StsClient extends SdkClient {
    static StsClientBuilder builder();
}

public interface StsClientBuilder {
    StsClientBuilder region(Region region);
    StsClientBuilder credentialsProvider(AwsCredentialsProvider credentialsProvider);
    StsClientBuilder endpointOverride(URI endpointOverride);
    StsClient build();
}

Basic Client Setup

StsClient stsClient = StsClient.builder()
    .region(Region.US_EAST_1)
    .build();

Core Operations

AssumeRole

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

AssumeRoleResponse assumeRole(AssumeRoleRequest request);

public interface AssumeRoleRequest {
    static AssumeRoleRequestBuilder builder();
    String roleArn();
    String roleSessionName();
    Integer durationSeconds();
    String policy();
    List<PolicyDescriptorType> policyArns();
    String externalId();
    String serialNumber();
    String tokenCode();
    List<Tag> tags();
    List<String> transitiveTagKeys();
    String sourceIdentity();
}

public interface AssumeRoleResponse {
    Credentials credentials();
    AssumedRoleUser assumedRoleUser();
    Integer packedPolicySize();
    String sourceIdentity();
}

Usage Example

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

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

AssumeRoleWithWebIdentity

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

AssumeRoleWithWebIdentityResponse assumeRoleWithWebIdentity(AssumeRoleWithWebIdentityRequest request);

public interface AssumeRoleWithWebIdentityRequest {
    static AssumeRoleWithWebIdentityRequestBuilder builder();
    String roleArn();
    String roleSessionName();
    String webIdentityToken();
    String providerId();
    String policy();
    List<PolicyDescriptorType> policyArns();
    Integer durationSeconds();
}

public interface AssumeRoleWithWebIdentityResponse {
    Credentials credentials();
    String subjectFromWebIdentityToken();
    AssumedRoleUser assumedRoleUser();
    Integer packedPolicySize();
    String provider();
    String audience();
    String sourceIdentity();
}

AssumeRoot

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

AssumeRootResponse assumeRoot(AssumeRootRequest request);

public interface AssumeRootRequest {
    static AssumeRootRequestBuilder builder();
    String targetPrincipal();
    PolicyDescriptorType taskPolicyArn();
    Integer durationSeconds();
}

public interface AssumeRootResponse {
    Credentials credentials();
    String sourceIdentity();
}

Usage Example

AssumeRootRequest request = AssumeRootRequest.builder()
    .targetPrincipal("123456789012")  // Member account ID
    .taskPolicyArn(PolicyDescriptorType.builder()
        .arn("arn:aws:iam::aws:policy/IAMAuditRootUserCredentials")
        .build())
    .durationSeconds(3600)
    .build();

AssumeRootResponse response = stsClient.assumeRoot(request);
Credentials credentials = response.credentials();

AssumeRoleWithSAML

Returns temporary credentials for users authenticated via SAML.

AssumeRoleWithSAMLResponse assumeRoleWithSAML(AssumeRoleWithSAMLRequest request);

public interface AssumeRoleWithSAMLRequest {
    static AssumeRoleWithSAMLRequestBuilder builder();
    String roleArn();
    String principalArn();
    String samlAssertion();
    String policy();
    List<PolicyDescriptorType> policyArns();
    Integer durationSeconds();
}

public interface AssumeRoleWithSAMLResponse {
    Credentials credentials();
    AssumedRoleUser assumedRoleUser();
    Integer packedPolicySize();
    String subject();
    String subjectType();
    String issuer();
    String audience();
    String nameQualifier();
    String sourceIdentity();
}

GetCallerIdentity

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

GetCallerIdentityResponse getCallerIdentity(GetCallerIdentityRequest request);

public interface GetCallerIdentityRequest {
    static GetCallerIdentityRequestBuilder builder();
}

public interface GetCallerIdentityResponse {
    String userId();
    String account(); 
    String arn();
}

Usage Example

GetCallerIdentityResponse response = stsClient.getCallerIdentity(
    GetCallerIdentityRequest.builder().build()
);

System.out.println("User ID: " + response.userId());
System.out.println("Account: " + response.account());
System.out.println("ARN: " + response.arn());

GetSessionToken

Returns temporary credentials for AWS account root or IAM users.

GetSessionTokenResponse getSessionToken(GetSessionTokenRequest request);

public interface GetSessionTokenRequest {
    static GetSessionTokenRequestBuilder builder();
    Integer durationSeconds();
    String serialNumber();
    String tokenCode();
}

public interface GetSessionTokenResponse {
    Credentials credentials();
}

GetFederationToken

Returns temporary credentials for federated users.

GetFederationTokenResponse getFederationToken(GetFederationTokenRequest request);

public interface GetFederationTokenRequest {
    static GetFederationTokenRequestBuilder builder();
    String name();
    String policy();
    List<PolicyDescriptorType> policyArns();
    Integer durationSeconds();
    List<Tag> tags();
}

public interface GetFederationTokenResponse {
    Credentials credentials();
    FederatedUser federatedUser();
    Integer packedPolicySize();
}

GetAccessKeyInfo

Returns the account identifier for the specified access key ID.

GetAccessKeyInfoResponse getAccessKeyInfo(GetAccessKeyInfoRequest request);

public interface GetAccessKeyInfoRequest {
    static GetAccessKeyInfoRequestBuilder builder();
    String accessKeyId();
}

public interface GetAccessKeyInfoResponse {
    String account();
}

DecodeAuthorizationMessage

Decodes additional information about the authorization status of requests.

DecodeAuthorizationMessageResponse decodeAuthorizationMessage(DecodeAuthorizationMessageRequest request);

public interface DecodeAuthorizationMessageRequest {
    static DecodeAuthorizationMessageRequestBuilder builder();
    String encodedMessage();
}

public interface DecodeAuthorizationMessageResponse {
    String decodedMessage();
}

Common Types

Credentials

public interface Credentials {
    String accessKeyId();
    String secretAccessKey();
    String sessionToken();
    Instant expiration();
}

AssumedRoleUser

public interface AssumedRoleUser {
    String assumedRoleId();
    String arn();
}

FederatedUser

public interface FederatedUser {
    String federatedUserId();
    String arn();
}

PolicyDescriptorType

public interface PolicyDescriptorType {
    static PolicyDescriptorTypeBuilder builder();
    String arn();
}

Tag

public interface Tag {
    static TagBuilder builder();
    String key();
    String value();
}

Exception Handling

All STS operations can throw the following exceptions:

public class ExpiredTokenException extends StsException {
    // The web identity token that was passed is expired or is not valid
}

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

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

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

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

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

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

public class RegionDisabledException extends StsException {
    // STS is not activated in the requested region for the account
}

Error Handling Example

try {
    AssumeRoleResponse response = stsClient.assumeRole(request);
    // Process successful response
} catch (ExpiredTokenException e) {
    // Handle expired token
    System.err.println("Token expired: " + e.getMessage());
} catch (MalformedPolicyDocumentException e) {
    // Handle policy document error
    System.err.println("Invalid policy: " + e.getMessage());
} catch (IdpCommunicationErrorException e) {
    // Handle identity provider communication error
    System.err.println("IdP communication error: " + e.getMessage());
} catch (StsException e) {
    // Handle other STS errors
    System.err.println("STS error: " + e.getMessage());
}

Install with Tessl CLI

npx tessl i tessl/maven-software-amazon-awssdk--sts

docs

client-operations.md

credential-providers.md

index.md

tile.json