tessl/maven-software-amazon-awssdk--auth

Authentication library providing comprehensive signing and credential management capabilities for AWS services.

Overview

Eval results

Files

Token Authentication

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

OAuth and Bearer token authentication support for modern AWS services requiring token-based authentication flows, including SSO and federated access scenarios.

Capabilities

SdkToken Interface

Base interface for SDK tokens providing token value and expiration information.

/**
 * Base interface for SDK tokens used in OAuth-based authentication
 * Provides token value and optional expiration time
 */
interface SdkToken extends TokenIdentity {
    /**
     * Get the token value
     * @return token string
     */
    String token();
    
    /**
     * Get token expiration time if available
     * @return Optional expiration instant
     */
    Optional<Instant> expirationTime();
    
    /**
     * Get the provider name that created this token
     * @return Optional provider name
     */
    Optional<String> providerName();
    
    /**
     * Get associated account ID if available
     * @return Optional account ID
     */
    Optional<String> accountId();
}

SdkTokenProvider Interface

Functional interface for loading SDK tokens with support for both synchronous and asynchronous resolution.

/**
 * Functional interface for loading SDK tokens
 * Supports both sync and async token resolution
 */
@FunctionalInterface
interface SdkTokenProvider extends IdentityProvider<TokenIdentity> {
    /**
     * Resolve token synchronously
     * @return SdkToken instance
     * @throws SdkClientException if token cannot be resolved
     */
    SdkToken resolveToken();
    
    /**
     * Return the identity type this provider handles
     * @return Class representing TokenIdentity
     */
    default Class<TokenIdentity> identityType() {
        return TokenIdentity.class;
    }
    
    /**
     * Resolve token asynchronously
     * @param request resolve identity request
     * @return CompletableFuture with resolved identity
     */
    default CompletableFuture<? extends TokenIdentity> resolveIdentity(ResolveIdentityRequest request) {
        return CompletableFuture.supplyAsync(() -> resolveToken());
    }
}

StaticTokenProvider

Token provider that returns a static, pre-configured token without any external lookups.

/**
 * Token provider that returns static token
 * Useful for testing or when token is known at compile time
 */
final class StaticTokenProvider implements SdkTokenProvider {
    /**
     * Create provider with static token
     * @param token static token to return
     * @return StaticTokenProvider instance
     */
    static StaticTokenProvider create(SdkToken token);
    
    SdkToken resolveToken();
}

Usage Examples:

import software.amazon.awssdk.auth.token.credentials.*;
import java.time.Instant;

// Create a custom token implementation
SdkToken myToken = new SdkToken() {
    @Override
    public String token() {
        return "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";
    }
    
    @Override
    public Optional<Instant> expirationTime() {
        return Optional.of(Instant.now().plusSeconds(3600));
    }
    
    @Override
    public Optional<String> providerName() {
        return Optional.of("MyTokenProvider");
    }
    
    @Override
    public Optional<String> accountId() {
        return Optional.of("123456789012");
    }
};

// Create static provider
StaticTokenProvider provider = StaticTokenProvider.create(myToken);
SdkToken resolvedToken = provider.resolveToken();

SdkTokenProviderChain

Chains multiple token providers with fallback behavior, trying each provider in order until one succeeds.

/**
 * Chains multiple token providers with fallback behavior
 * Tries providers in order until one successfully returns a token
 */
class SdkTokenProviderChain implements SdkTokenProvider, SdkAutoCloseable {
    /**
     * Create provider chain from varargs
     * @param providers token providers in order
     * @return SdkTokenProviderChain instance
     */
    static SdkTokenProviderChain of(SdkTokenProvider... providers);
    
    /**
     * Create builder for advanced configuration
     * @return Builder instance
     */
    static Builder builder();
    
    SdkToken resolveToken();
    void close();
    
    interface Builder extends CopyableBuilder<Builder, SdkTokenProviderChain> {
        /**
         * Set the list of token providers
         * @param tokenProviders collection of providers
         * @return builder instance
         */
        Builder tokenProviders(Collection<? extends SdkTokenProvider> tokenProviders);
        
        /**
         * Set token providers from varargs
         * @param tokenProviders providers to add
         * @return builder instance
         */
        Builder tokenProviders(SdkTokenProvider... tokenProviders);
        
        /**
         * Add a single token provider to the chain
         * @param tokenProvider provider to add
         * @return builder instance
         */
        Builder addTokenProvider(SdkTokenProvider tokenProvider);
        
        SdkTokenProviderChain build();
    }
}

DefaultAwsTokenProvider

Default AWS token provider chain that checks multiple token sources in order, including profile-based SSO tokens.

/**
 * Default token provider chain for AWS token resolution
 * Checks profile-based SSO configurations and other token sources
 */
final class DefaultAwsTokenProvider implements SdkTokenProvider, SdkAutoCloseable {
    /**
     * Create default token provider
     * @return DefaultAwsTokenProvider instance
     */
    static DefaultAwsTokenProvider create();
    
    /**
     * Create builder for custom configuration
     * @return Builder instance
     */
    static Builder builder();
    
    SdkToken resolveToken();
    void close();
    
    interface Builder extends CopyableBuilder<Builder, DefaultAwsTokenProvider> {
        /**
         * Override profile file location
         * @param profileFile profile file supplier
         * @return builder instance
         */
        Builder profileFile(Supplier<ProfileFile> profileFile);
        
        /**
         * Set specific profile name to use
         * @param profileName profile name
         * @return builder instance
         */
        Builder profileName(String profileName);
        
        DefaultAwsTokenProvider build();
    }
}

Usage Examples:

import software.amazon.awssdk.auth.token.credentials.aws.DefaultAwsTokenProvider;

// Use default token provider (for SSO)
try (DefaultAwsTokenProvider provider = DefaultAwsTokenProvider.create()) {
    SdkToken token = provider.resolveToken();
    // Use token for authenticated requests
}

// Custom configuration for specific profile
try (DefaultAwsTokenProvider provider = DefaultAwsTokenProvider.builder()
        .profileName("sso-profile")
        .build()) {
    SdkToken token = provider.resolveToken();
}

ProfileTokenProvider

Loads tokens from AWS profile files, particularly useful for SSO (Single Sign-On) configurations.

/**
 * Loads tokens from AWS profile files
 * Primarily used for SSO token configurations
 */
class ProfileTokenProvider implements SdkTokenProvider, SdkAutoCloseable {
    /**
     * Create provider for default profile
     * @return ProfileTokenProvider instance
     */
    static ProfileTokenProvider create();
    
    /**
     * Create provider for specific profile
     * @param profileName name of profile to use
     * @return ProfileTokenProvider instance
     */
    static ProfileTokenProvider create(String profileName);
    
    /**
     * Create builder for advanced configuration
     * @return Builder instance
     */
    static Builder builder();
    
    SdkToken resolveToken();
    void close();
    
    interface Builder extends CopyableBuilder<Builder, ProfileTokenProvider> {
        /**
         * Override profile file location
         * @param profileFile profile file supplier
         * @return builder instance
         */
        Builder profileFile(Supplier<ProfileFile> profileFile);
        
        /**
         * Set profile name to use
         * @param profileName profile name
         * @return builder instance
         */
        Builder profileName(String profileName);
        
        ProfileTokenProvider build();
    }
}

Usage Examples:

import software.amazon.awssdk.auth.token.credentials.ProfileTokenProvider;

// Load token from default profile
try (ProfileTokenProvider provider = ProfileTokenProvider.create()) {
    SdkToken token = provider.resolveToken();
}

// Load token from specific SSO profile
try (ProfileTokenProvider provider = ProfileTokenProvider.create("my-sso-profile")) {
    SdkToken token = provider.resolveToken();
    
    // Check token expiration
    if (token.expirationTime().isPresent()) {
        Instant expiry = token.expirationTime().get();
        if (expiry.isBefore(Instant.now().plusMinutes(5))) {
            // Token expires soon, consider refreshing
            logger.warn("Token expires in less than 5 minutes");
        }
    }
}

Factory Classes

Utility classes for creating token providers with shared configuration.

/**
 * Factory for creating child profile token providers
 */
class ChildProfileTokenProviderFactory {
    /**
     * Create token provider for child profile
     * @param profileFile profile file containing configuration
     * @param profileName name of profile to use
     * @return SdkTokenProvider instance
     */
    SdkTokenProvider create(ProfileFile profileFile, String profileName);
}

/**
 * Properties for configuring token provider factories
 */
class SdkTokenProviderFactoryProperties {
    /**
     * Get profile file supplier
     * @return profile file supplier
     */
    Supplier<ProfileFile> profileFile();
    
    /**
     * Get profile name
     * @return profile name
     */
    String profileName();
}

Token Signing

Legacy Bearer token signer implementation (deprecated in favor of http-auth module).

/**
 * Signer for Bearer token authorization (RFC 6750)
 * @deprecated Use BearerHttpSigner from 'http-auth' module instead
 */
@Deprecated
final class BearerTokenSigner implements Signer {
    /**
     * Create bearer token signer
     * @return BearerTokenSigner instance
     */
    static BearerTokenSigner create();
    
    /**
     * Sign request with token parameters
     * @param request HTTP request to sign
     * @param tokenSignerParams token signing parameters
     * @return signed HTTP request
     */
    SdkHttpFullRequest sign(SdkHttpFullRequest request, TokenSignerParams tokenSignerParams);
    
    /**
     * Sign request using execution attributes
     * @param request HTTP request to sign
     * @param executionAttributes execution context attributes
     * @return signed HTTP request
     */
    SdkHttpFullRequest sign(SdkHttpFullRequest request, ExecutionAttributes executionAttributes);
}

/**
 * Token-specific execution attributes for signing context
 */
class SdkTokenExecutionAttribute {
    /**
     * Execution attribute for SDK token
     */
    ExecutionAttribute<SdkToken> SDK_TOKEN;
}

SSO Integration

Token providers integrate with AWS SSO for seamless single sign-on experiences:

Profile Configuration Example:

[profile my-sso-profile]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = MyRole
region = us-west-2

Usage with SSO:

// Token provider automatically handles SSO token refresh
DefaultAwsTokenProvider ssoProvider = DefaultAwsTokenProvider.builder()
    .profileName("my-sso-profile")
    .build();

try {
    SdkToken token = ssoProvider.resolveToken();
    // Token is automatically obtained from SSO cache or triggers SSO flow
} catch (SdkClientException e) {
    if (e.getMessage().contains("SSO")) {
        // May need to run 'aws sso login' command
        logger.info("SSO login required: aws sso login --profile my-sso-profile");
    }
}

Error Handling

Token resolution may encounter various error conditions:

try {
    SdkToken token = provider.resolveToken();
} catch (SdkClientException e) {
    // Token resolution failed - check cause for specific error
    if (e.getMessage().contains("expired")) {
        // Token or SSO session expired
    } else if (e.getMessage().contains("not found")) {
        // Profile or token cache not found
    }
}

Common error scenarios:

SSO session expired: Need to re-authenticate with SSO provider
Profile not found: Specified profile doesn't exist in configuration files
Token cache missing: SSO tokens not cached, may need to login
Network errors: Unable to reach SSO endpoints for token refresh
Permission denied: Insufficient permissions for SSO role assumption

Utility Classes

TokenUtils Class

Utility class providing helper methods for working with SDK tokens and token providers.

/**
 * Utility class for SDK token operations
 * Provides conversion and validation methods for token-based authentication
 */
final class TokenUtils {
    /**
     * Convert TokenIdentity to SdkToken
     * @param tokenIdentity token identity to convert
     * @return SdkToken instance
     */
    static SdkToken toSdkToken(TokenIdentity tokenIdentity);
    
    /**
     * Convert generic identity provider to SDK token provider
     * @param identityProvider generic identity provider for tokens
     * @return SdkTokenProvider instance
     */
    static SdkTokenProvider toSdkTokenProvider(
        IdentityProvider<? extends TokenIdentity> identityProvider);
}

Usage Examples:

import software.amazon.awssdk.auth.token.credentials.TokenUtils;

// Convert identity to SDK token
TokenIdentity identity = // ... obtain token identity
SdkToken sdkToken = TokenUtils.toSdkToken(identity);

// Convert identity provider to SDK token provider
IdentityProvider<TokenIdentity> genericProvider = // ... 
SdkTokenProvider tokenProvider = TokenUtils.toSdkTokenProvider(genericProvider);

// Use converted token provider
SdkToken token = tokenProvider.resolveToken();
System.out.println("Token: " + token.token());

Install with Tessl CLI

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

docs

credential-management.md

credential-providers.md

index.md

request-signing.md

token-authentication.md

tile.json

tessl/maven-software-amazon-awssdk--auth