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

Session Token Operations

Name: tessl/maven-com-amazonaws--aws-java-sdk-sts
Author: tessl

Session token management for MFA-protected operations and temporary credential generation for existing IAM users. Session tokens enable secure access to MFA-required operations and provide temporary credentials with the same permissions as the calling user.

Capabilities

Session Token Generation

Returns temporary credentials for IAM users, typically used for MFA-protected operations.

/**
 * Returns temporary security credentials for IAM users
 * @param getSessionTokenRequest Request containing optional MFA information and duration
 * @return Result containing temporary credentials with same permissions as calling user
 * @throws RegionDisabledException If STS not activated in requested region
 */
GetSessionTokenResult getSessionToken(GetSessionTokenRequest getSessionTokenRequest);

/**
 * Simplified method form for getting session token with default parameters
 * @return Result containing temporary credentials
 */
GetSessionTokenResult getSessionToken();

Request and Result Types:

public class GetSessionTokenRequest extends AmazonWebServiceRequest {
    public GetSessionTokenRequest();
    
    // Optional parameters
    public Integer getDurationSeconds();
    public void setDurationSeconds(Integer durationSeconds);
    public GetSessionTokenRequest withDurationSeconds(Integer durationSeconds);
    
    public String getSerialNumber();
    public void setSerialNumber(String serialNumber);
    public GetSessionTokenRequest withSerialNumber(String serialNumber);
    
    public String getTokenCode();
    public void setTokenCode(String tokenCode);
    public GetSessionTokenRequest withTokenCode(String tokenCode);
}

public class GetSessionTokenResult {
    public Credentials getCredentials();
    public void setCredentials(Credentials credentials);
}

Usage Examples:

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

// Basic session token request
GetSessionTokenResult result = stsClient.getSessionToken();
Credentials sessionCredentials = result.getCredentials();

System.out.println("Session Access Key: " + sessionCredentials.getAccessKeyId());
System.out.println("Session Secret Key: " + sessionCredentials.getSecretAccessKey());
System.out.println("Session Token: " + sessionCredentials.getSessionToken());
System.out.println("Expires: " + sessionCredentials.getExpiration());

// Session token with custom duration
GetSessionTokenRequest durationRequest = new GetSessionTokenRequest()
    .withDurationSeconds(7200); // 2 hours

GetSessionTokenResult durationResult = stsClient.getSessionToken(durationRequest);

// Session token with MFA authentication
GetSessionTokenRequest mfaRequest = new GetSessionTokenRequest()
    .withSerialNumber("arn:aws:iam::123456789012:mfa/username")
    .withTokenCode("123456")
    .withDurationSeconds(3600); // 1 hour

GetSessionTokenResult mfaResult = stsClient.getSessionToken(mfaRequest);
Credentials mfaCredentials = mfaResult.getCredentials();

Session Token Use Cases

MFA-Protected Operations

Session tokens are primarily used to enable MFA-protected API operations:

/**
 * Example service that uses session tokens for MFA-protected operations
 */
public class MFAProtectedService {
    private final AWSSecurityTokenService stsClient;
    
    public MFAProtectedService(AWSSecurityTokenService stsClient) {
        this.stsClient = stsClient;
    }
    
    /**
     * Get session token with MFA for accessing MFA-protected resources
     */
    public Credentials getMFASessionToken(String mfaSerial, String mfaToken) {
        GetSessionTokenRequest request = new GetSessionTokenRequest()
            .withSerialNumber(mfaSerial)
            .withTokenCode(mfaToken)
            .withDurationSeconds(3600);
        
        GetSessionTokenResult result = stsClient.getSessionToken(request);
        return result.getCredentials();
    }
    
    /**
     * Example of using MFA session credentials for sensitive operations
     */
    public void performSensitiveOperation(String mfaSerial, String mfaToken) {
        // Get MFA session token
        Credentials mfaCredentials = getMFASessionToken(mfaSerial, mfaToken);
        
        // Create new service clients with MFA credentials
        AWSCredentials awsCredentials = new BasicSessionCredentials(
            mfaCredentials.getAccessKeyId(),
            mfaCredentials.getSecretAccessKey(),
            mfaCredentials.getSessionToken()
        );
        
        // Now use these credentials for MFA-protected operations
        // For example: IAM operations, sensitive S3 operations, etc.
    }
}

Temporary Credential Distribution

Session tokens can be used to provide temporary credentials to applications:

/**
 * Example application credential manager
 */
public class ApplicationCredentialManager {
    private final AWSSecurityTokenService stsClient;
    
    public ApplicationCredentialManager() {
        this.stsClient = AWSSecurityTokenServiceClientBuilder.defaultClient();
    }
    
    /**
     * Get temporary credentials for application use
     */
    public Credentials getTemporaryCredentials(int durationSeconds) {
        GetSessionTokenRequest request = new GetSessionTokenRequest()
            .withDurationSeconds(durationSeconds);
        
        GetSessionTokenResult result = stsClient.getSessionToken(request);
        return result.getCredentials();
    }
    
    /**
     * Refresh credentials before they expire
     */
    public Credentials refreshCredentials(Credentials currentCredentials) {
        // Check if credentials are close to expiration
        Date expiration = currentCredentials.getExpiration();
        Date now = new Date();
        long timeToExpiration = expiration.getTime() - now.getTime();
        
        // Refresh if less than 15 minutes remaining
        if (timeToExpiration < 15 * 60 * 1000) {
            return getTemporaryCredentials(3600); // 1 hour
        }
        
        return currentCredentials; // Still valid
    }
}

Session Duration and Limitations

Duration Constraints

Session token duration depends on the calling credentials:

IAM User credentials: 900 seconds (15 minutes) to 129,600 seconds (36 hours), default 43,200 seconds (12 hours)
Root user credentials: 900 seconds (15 minutes) to 3,600 seconds (1 hour), default 3,600 seconds (1 hour)

// Examples of different duration configurations
public class SessionDurationExamples {
    
    public void demonstrateDurationLimits() {
        AWSSecurityTokenService stsClient = AWSSecurityTokenServiceClientBuilder.defaultClient();
        
        // Minimum duration (15 minutes)
        GetSessionTokenRequest minRequest = new GetSessionTokenRequest()
            .withDurationSeconds(900);
        
        // Default duration (12 hours for IAM users)
        GetSessionTokenRequest defaultRequest = new GetSessionTokenRequest();
        
        // Maximum duration for IAM users (36 hours)
        GetSessionTokenRequest maxRequest = new GetSessionTokenRequest()
            .withDurationSeconds(129600);
        
        // For root users, maximum is 1 hour
        GetSessionTokenRequest rootMaxRequest = new GetSessionTokenRequest()
            .withDurationSeconds(3600);
    }
}

Permission Characteristics

Session tokens have specific permission characteristics:

Same permissions as calling user - Session tokens inherit all permissions from the IAM user or root user that called GetSessionToken
Cannot call IAM operations unless MFA authentication is included in the request
Can only call specific STS operations - Only AssumeRole and GetCallerIdentity are allowed
No session policies - Unlike AssumeRole or GetFederationToken, session tokens cannot be restricted with session policies

/**
 * Example demonstrating session token permission characteristics
 */
public class SessionTokenPermissions {
    
    public void demonstratePermissionLimitations() {
        // Get session token without MFA
        GetSessionTokenResult result = stsClient.getSessionToken();
        Credentials sessionCredentials = result.getCredentials();
        
        // Create new STS client with session credentials
        AWSSecurityTokenService sessionStsClient = AWSSecurityTokenServiceClientBuilder.standard()
            .withCredentials(new BasicSessionCredentials(
                sessionCredentials.getAccessKeyId(),
                sessionCredentials.getSecretAccessKey(),
                sessionCredentials.getSessionToken()
            ))
            .build();
        
        try {
            // This will work - GetCallerIdentity is allowed
            GetCallerIdentityResult identity = sessionStsClient.getCallerIdentity(
                new GetCallerIdentityRequest()
            );
            System.out.println("Caller ARN: " + identity.getArn());
            
            // This will work - AssumeRole is allowed  
            AssumeRoleResult assumeResult = sessionStsClient.assumeRole(
                new AssumeRoleRequest()
                    .withRoleArn("arn:aws:iam::123456789012:role/MyRole")
                    .withRoleSessionName("SessionFromSessionToken")
            );
            
            // These operations will NOT work without MFA:
            // - GetFederationToken
            // - GetSessionToken
            // - Most IAM operations
            
        } catch (Exception e) {
            System.out.println("Operation failed: " + e.getMessage());
        }
    }
}

Best Practices

/**
 * Best practices for session token usage
 */
public class SessionTokenBestPractices {
    
    /**
     * Recommended pattern for MFA-enabled applications
     */
    public class MFAEnabledApplication {
        private Credentials currentCredentials;
        private Date credentialsExpiration;
        
        public void authenticateWithMFA(String mfaSerial, String mfaToken) {
            GetSessionTokenRequest request = new GetSessionTokenRequest()
                .withSerialNumber(mfaSerial)
                .withTokenCode(mfaToken)
                .withDurationSeconds(3600); // 1 hour for MFA sessions
            
            GetSessionTokenResult result = stsClient.getSessionToken(request);
            this.currentCredentials = result.getCredentials();
            this.credentialsExpiration = result.getCredentials().getExpiration();
        }
        
        public boolean needsRefresh() {
            if (currentCredentials == null) return true;
            
            Date now = new Date();
            long timeToExpiration = credentialsExpiration.getTime() - now.getTime();
            
            // Refresh if less than 5 minutes remaining
            return timeToExpiration < 5 * 60 * 1000;
        }
        
        public AWSCredentials getCredentials() {
            if (needsRefresh()) {
                throw new IllegalStateException("Credentials need refresh");
            }
            
            return new BasicSessionCredentials(
                currentCredentials.getAccessKeyId(),
                currentCredentials.getSecretAccessKey(),
                currentCredentials.getSessionToken()
            );
        }
    }
    
    /**
     * Pattern for long-running applications
     */
    public class LongRunningApplication {
        private static final int DEFAULT_DURATION = 43200; // 12 hours
        private static final int REFRESH_THRESHOLD = 1800; // 30 minutes
        
        private Credentials credentials;
        private ScheduledExecutorService scheduler;
        
        public void start() {
            refreshCredentials();
            
            // Schedule automatic refresh
            scheduler = Executors.newScheduledThreadPool(1);
            scheduler.scheduleAtFixedRate(
                this::refreshCredentialsIfNeeded,
                REFRESH_THRESHOLD,
                REFRESH_THRESHOLD,
                TimeUnit.SECONDS
            );
        }
        
        private void refreshCredentials() {
            GetSessionTokenRequest request = new GetSessionTokenRequest()
                .withDurationSeconds(DEFAULT_DURATION);
            
            GetSessionTokenResult result = stsClient.getSessionToken(request);
            this.credentials = result.getCredentials();
        }
        
        private void refreshCredentialsIfNeeded() {
            Date now = new Date();
            long timeToExpiration = credentials.getExpiration().getTime() - now.getTime();
            
            if (timeToExpiration < REFRESH_THRESHOLD * 1000) {
                refreshCredentials();
            }
        }
        
        public void shutdown() {
            if (scheduler != null) {
                scheduler.shutdown();
            }
        }
    }
}

Install with Tessl CLI

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

docs