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

Credential Providers

Name: tessl/maven-software-amazon-awssdk--sts
Author: tessl

The STS credential providers offer high-level abstractions for obtaining and managing temporary AWS credentials. They automatically handle credential caching, refresh, and lifecycle management, integrating seamlessly with the AWS SDK credential provider chain.

Core Imports

import software.amazon.awssdk.services.sts.auth.*;
import software.amazon.awssdk.services.sts.model.*;
import software.amazon.awssdk.auth.credentials.AwsCredentials;
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
import software.amazon.awssdk.core.SdkAutoCloseable;
import java.time.Duration;
import java.nio.file.Path;
import java.util.function.Consumer;
import java.util.function.Supplier;

Base Credential Provider

StsCredentialsProvider

Abstract base class for all STS-based credential providers.

public abstract class StsCredentialsProvider implements AwsCredentialsProvider, SdkAutoCloseable {
    public abstract AwsCredentials resolveCredentials();
    public void close();
    public Duration staleTime();
    public Duration prefetchTime();
    
    public abstract static class BaseBuilder<B extends BaseBuilder<B, T>, T extends ToCopyableBuilder<B, T>> {
        public B stsClient(StsClient stsClient);
        public B asyncCredentialUpdateEnabled(Boolean asyncCredentialUpdateEnabled);
        public B staleTime(Duration staleTime);
        public B prefetchTime(Duration prefetchTime);
    }
}

Configuration Options

staleTime: Time before credentials are considered stale (default: 1 minute)
prefetchTime: Time before expiration to start refreshing credentials (default: 5 minutes)
asyncCredentialUpdateEnabled: Enable asynchronous credential refresh (default: false)

Assume Role Credential Provider

StsAssumeRoleCredentialsProvider

Provides credentials by assuming an IAM role using the AssumeRole operation.

public final class StsAssumeRoleCredentialsProvider extends StsCredentialsProvider
    implements ToCopyableBuilder<StsAssumeRoleCredentialsProvider.Builder, StsAssumeRoleCredentialsProvider> {
    
    public static Builder builder();
    
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsAssumeRoleCredentialsProvider> {
        Builder refreshRequest(AssumeRoleRequest assumeRoleRequest);
        Builder refreshRequest(Supplier<AssumeRoleRequest> assumeRoleRequestSupplier);
        Builder refreshRequest(Consumer<AssumeRoleRequest.Builder> assumeRoleRequest);
        StsAssumeRoleCredentialsProvider build();
    }
}

Usage Example

StsAssumeRoleCredentialsProvider credentialsProvider = 
    StsAssumeRoleCredentialsProvider.builder()
        .refreshRequest(AssumeRoleRequest.builder()
            .roleArn("arn:aws:iam::123456789012:role/MyRole")
            .roleSessionName("MySession")
            .durationSeconds(3600)
            .build())
        .staleTime(Duration.ofMinutes(2))
        .prefetchTime(Duration.ofMinutes(10))
        .build();

AwsCredentials credentials = credentialsProvider.resolveCredentials();

Web Identity Credential Providers

StsAssumeRoleWithWebIdentityCredentialsProvider

Provides credentials by assuming an IAM role using web identity tokens (OAuth, OpenID Connect).

public final class StsAssumeRoleWithWebIdentityCredentialsProvider extends StsCredentialsProvider
    implements ToCopyableBuilder<StsAssumeRoleWithWebIdentityCredentialsProvider.Builder, StsAssumeRoleWithWebIdentityCredentialsProvider> {
    
    public static Builder builder();
    
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsAssumeRoleWithWebIdentityCredentialsProvider> {
        Builder refreshRequest(AssumeRoleWithWebIdentityRequest assumeRoleWithWebIdentityRequest);
        Builder refreshRequest(Supplier<AssumeRoleWithWebIdentityRequest> assumeRoleWithWebIdentityRequestSupplier);
        Builder refreshRequest(Consumer<AssumeRoleWithWebIdentityRequest.Builder> assumeRoleWithWebIdentityRequest);
        StsAssumeRoleWithWebIdentityCredentialsProvider build();
    }
}

StsWebIdentityTokenFileCredentialsProvider

Reads web identity tokens from a file and uses them to assume a role.

public final class StsWebIdentityTokenFileCredentialsProvider extends StsCredentialsProvider
    implements ToCopyableBuilder<StsWebIdentityTokenFileCredentialsProvider.Builder, StsWebIdentityTokenFileCredentialsProvider> {
    
    public static Builder builder();
    
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsWebIdentityTokenFileCredentialsProvider> {
        Builder stsClient(StsClient stsClient);
        Builder roleArn(String roleArn);
        Builder roleSessionName(String roleSessionName);
        Builder webIdentityTokenFile(Path webIdentityTokenFile);
        Builder refreshRequest(AssumeRoleWithWebIdentityRequest assumeRoleWithWebIdentityRequest);
        Builder refreshRequest(Supplier<AssumeRoleWithWebIdentityRequest> assumeRoleWithWebIdentityRequestSupplier);
        Builder refreshRequest(Consumer<AssumeRoleWithWebIdentityRequest.Builder> assumeRoleWithWebIdentityRequest);
        StsWebIdentityTokenFileCredentialsProvider build();
    }
}

Usage Example

StsWebIdentityTokenFileCredentialsProvider credentialsProvider = 
    StsWebIdentityTokenFileCredentialsProvider.builder()
        .roleArn("arn:aws:iam::123456789012:role/WebIdentityRole")
        .roleSessionName("WebIdentitySession")
        .webIdentityTokenFile(Paths.get("/tmp/web-identity-token"))
        .build();

AwsCredentials credentials = credentialsProvider.resolveCredentials();

SAML Credential Provider

StsAssumeRoleWithSamlCredentialsProvider

Provides credentials by assuming an IAM role using SAML assertions.

public final class StsAssumeRoleWithSamlCredentialsProvider extends StsCredentialsProvider
    implements ToCopyableBuilder<StsAssumeRoleWithSamlCredentialsProvider.Builder, StsAssumeRoleWithSamlCredentialsProvider> {
    
    public static Builder builder();
    
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsAssumeRoleWithSamlCredentialsProvider> {
        Builder refreshRequest(AssumeRoleWithSAMLRequest assumeRoleWithSAMLRequest);
        Builder refreshRequest(Supplier<AssumeRoleWithSAMLRequest> assumeRoleWithSAMLRequestSupplier);
        Builder refreshRequest(Consumer<AssumeRoleWithSAMLRequest.Builder> assumeRoleWithSAMLRequest);
        StsAssumeRoleWithSamlCredentialsProvider build();
    }
}

Federation Token Credential Provider

StsGetFederationTokenCredentialsProvider

Provides credentials by obtaining federation tokens for temporary access.

public class StsGetFederationTokenCredentialsProvider extends StsCredentialsProvider
    implements ToCopyableBuilder<StsGetFederationTokenCredentialsProvider.Builder, StsGetFederationTokenCredentialsProvider> {
    
    public static Builder builder();
    
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsGetFederationTokenCredentialsProvider> {
        Builder refreshRequest(GetFederationTokenRequest getFederationTokenRequest);
        Builder refreshRequest(Consumer<GetFederationTokenRequest.Builder> getFederationTokenRequest);
        StsGetFederationTokenCredentialsProvider build();
    }
}

Usage Example

StsGetFederationTokenCredentialsProvider credentialsProvider = 
    StsGetFederationTokenCredentialsProvider.builder()
        .refreshRequest(GetFederationTokenRequest.builder()
            .name("FederatedUser")
            .policy("{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":\"s3:*\",\"Resource\":\"*\"}]}")
            .durationSeconds(3600)
            .build())
        .build();

AwsCredentials credentials = credentialsProvider.resolveCredentials();

Session Token Credential Provider

StsGetSessionTokenCredentialsProvider

Provides credentials by obtaining session tokens for temporary access with MFA.

public class StsGetSessionTokenCredentialsProvider extends StsCredentialsProvider
    implements ToCopyableBuilder<StsGetSessionTokenCredentialsProvider.Builder, StsGetSessionTokenCredentialsProvider> {
    
    public static Builder builder();
    
    public static interface Builder extends StsCredentialsProvider.BaseBuilder<Builder, StsGetSessionTokenCredentialsProvider> {
        Builder refreshRequest(GetSessionTokenRequest getSessionTokenRequest);
        Builder refreshRequest(Consumer<GetSessionTokenRequest.Builder> getSessionTokenRequest);
        StsGetSessionTokenCredentialsProvider build();
    }
}

Usage Example with MFA

StsGetSessionTokenCredentialsProvider credentialsProvider = 
    StsGetSessionTokenCredentialsProvider.builder()
        .refreshRequest(GetSessionTokenRequest.builder()
            .durationSeconds(3600)
            .serialNumber("arn:aws:iam::123456789012:mfa/user")
            .tokenCode("123456")
            .build())
        .build();

AwsCredentials credentials = credentialsProvider.resolveCredentials();

Helper Classes

SessionCredentialsHolder

Container for credentials with session information.

public class SessionCredentialsHolder {
    public AwsSessionCredentials sessionCredentials();
    public Instant sessionCredentialExpiration();
    public boolean stale(Duration staleTime);
    public boolean needsRefresh(Duration prefetchTime);
}

Integration with AWS SDK

All credential providers implement AwsCredentialsProvider and can be used with any AWS service client:

S3Client s3Client = S3Client.builder()
    .credentialsProvider(credentialsProvider)
    .region(Region.US_EAST_1)
    .build();

Environment Variables

The credential providers respect these environment variables:

AWS_WEB_IDENTITY_TOKEN_FILE: Path to web identity token file
AWS_ROLE_ARN: ARN of the role to assume
AWS_ROLE_SESSION_NAME: Session name for role assumption

Best Practices

Resource Management

Always close credential providers when done:

try (StsAssumeRoleCredentialsProvider provider = 
         StsAssumeRoleCredentialsProvider.builder()
             .refreshRequest(request)
             .build()) {
    
    AwsCredentials credentials = provider.resolveCredentials();
    // Use credentials
}

Async Credential Updates

Enable asynchronous credential refresh for better performance:

StsAssumeRoleCredentialsProvider provider = 
    StsAssumeRoleCredentialsProvider.builder()
        .refreshRequest(request)
        .asyncCredentialUpdateEnabled(true)
        .build();

Custom Timing Configuration

Configure stale and prefetch times based on your application needs:

StsAssumeRoleCredentialsProvider provider = 
    StsAssumeRoleCredentialsProvider.builder()
        .refreshRequest(request)
        .staleTime(Duration.ofMinutes(5))        // Consider stale after 5 minutes
        .prefetchTime(Duration.ofMinutes(15))    // Start refresh 15 minutes before expiry
        .build();

Error Handling

Credential providers throw StsException and its subclasses:

try {
    AwsCredentials credentials = provider.resolveCredentials();
} catch (ExpiredTokenException e) {
    // Handle expired token
} catch (StsException e) {
    // Handle other STS errors
}

Install with Tessl CLI

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

docs

client-operations.md

credential-providers.md

index.md

tile.json

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