tessl/maven-software-amazon-smithy--smithy-aws-endpoints

AWS specific components for managing endpoints in Smithy

Overview

Eval results

Files

Authentication Utilities

Name: tessl/maven-software-amazon-smithy--smithy-aws-endpoints
Author: tessl

The authentication utilities provide helper methods for constructing AWS authentication schemes in endpoint rules, supporting SigV4, SigV4a, and related authentication mechanisms.

Capabilities

EndpointAuthUtils Class

Utilities for constructing and validating AWS-specific authentication components for rule-sets.

/**
 * Utilities for constructing and validating AWS-specific authentication components for rule-sets.
 */
public final class EndpointAuthUtils {
    /**
     * Adds SigV4 authentication to the provided endpoint builder
     * @param builder The endpoint builder to augment
     * @param signingRegion The signing region to use when signing
     * @param signingService The name of the service to sign with
     * @return The updated endpoint builder
     */
    public static Endpoint.Builder sigv4(Endpoint.Builder builder, Literal signingRegion, Literal signingService);
    
    /**
     * Adds SigV4a authentication to the provided endpoint builder
     * @param builder The endpoint builder to augment  
     * @param signingRegionSet The set of signing regions to use when signing
     * @param signingService The name of the service to sign with
     * @return The updated endpoint builder
     */
    public static Endpoint.Builder sigv4a(Endpoint.Builder builder, List<Literal> signingRegionSet, Literal signingService);
    
    /**
     * Returns if a given auth scheme is equivalent to aws.auth#sigv4
     * @param authScheme Name of the auth scheme
     * @return Whether the auth scheme is equivalent to aws.auth#sigv4
     */
    public static boolean isSigV4EquivalentAuthScheme(String authScheme);
    
    /**
     * Returns if a given auth scheme is equivalent to aws.auth#sigv4a
     * @param authScheme Name of the auth scheme
     * @return Whether the auth scheme is equivalent to aws.auth#sigv4a
     */
    public static boolean isSigV4AEquivalentAuthScheme(String authScheme);
}

Authentication Scheme Validators

The package provides validators for AWS authentication schemes used in endpoint rules.

/**
 * Validator for SigV4 authentication schemes
 */
public static final class SigV4SchemeValidator implements AuthSchemeValidator {
    /**
     * Tests if this validator applies to the given authentication scheme name
     * @param name The authentication scheme name
     * @return True if this validator should be used for the scheme
     */
    public boolean test(String name);
    
    /**
     * Validates SigV4 authentication configuration
     * @param authScheme The authentication scheme parameter set
     * @param sourceLocation The location of the authorization scheme
     * @param emitter Function to emit validation events for failures
     * @return List of validation events (errors/warnings)
     */
    public List<ValidationEvent> validateScheme(
        Map<Identifier, Literal> authScheme,
        FromSourceLocation sourceLocation,
        BiFunction<FromSourceLocation, String, ValidationEvent> emitter);
}

/**
 * Validator for SigV4a authentication schemes  
 */
public static final class SigV4aSchemeValidator implements AuthSchemeValidator {
    /**
     * Tests if this validator applies to the given authentication scheme name
     * @param name The authentication scheme name
     * @return True if this validator should be used for the scheme
     */
    public boolean test(String name);
    
    /**
     * Validates SigV4a authentication configuration
     * @param authScheme The authentication scheme parameter set
     * @param sourceLocation The location of the authorization scheme
     * @param emitter Function to emit validation events for failures
     * @return List of validation events (errors/warnings)
     */
    public List<ValidationEvent> validateScheme(
        Map<Identifier, Literal> authScheme,
        FromSourceLocation sourceLocation,
        BiFunction<FromSourceLocation, String, ValidationEvent> emitter);
}

/**
 * Validator for SigV4 sub-scheme authentication (e.g., sigv4-s3express)
 */
public static final class SigV4SubSchemeValidator implements AuthSchemeValidator {
    /**
     * Tests if this validator applies to the given authentication scheme name
     * @param name The authentication scheme name
     * @return True if this validator should be used for the scheme
     */
    public boolean test(String name);
    
    /**
     * Validates SigV4 sub-scheme authentication configuration
     * @param authScheme The authentication scheme parameter set
     * @param sourceLocation The location of the authorization scheme
     * @param emitter Function to emit validation events for failures
     * @return List of validation events (errors/warnings)
     */
    public List<ValidationEvent> validateScheme(
        Map<Identifier, Literal> authScheme,
        FromSourceLocation sourceLocation,
        BiFunction<FromSourceLocation, String, ValidationEvent> emitter);
}

/**
 * Validator for beta authentication schemes
 */
public static final class BetaSchemeValidator implements AuthSchemeValidator {
    /**
     * Tests if this validator applies to the given authentication scheme name
     * @param name The authentication scheme name
     * @return True if this validator should be used for the scheme
     */
    public boolean test(String name);
    
    /**
     * Validates beta authentication scheme configuration
     * @param authScheme The authentication scheme parameter set
     * @param sourceLocation The location of the authorization scheme
     * @param emitter Function to emit validation events for failures
     * @return List of validation events (errors/warnings)
     */
    public List<ValidationEvent> validateScheme(
        Map<Identifier, Literal> authScheme,
        FromSourceLocation sourceLocation,
        BiFunction<FromSourceLocation, String, ValidationEvent> emitter);
}

Usage Examples:

import software.amazon.smithy.rulesengine.aws.language.functions.EndpointAuthUtils;
import software.amazon.smithy.rulesengine.language.Endpoint;
import software.amazon.smithy.rulesengine.language.syntax.expressions.literal.Literal;

// Build an endpoint with SigV4 authentication
Endpoint.Builder endpointBuilder = Endpoint.builder()
    .url("https://service.us-east-1.amazonaws.com");

// Add SigV4 authentication
Endpoint endpoint = EndpointAuthUtils.sigv4(
    endpointBuilder,
    Literal.of("us-east-1"),    // signing region
    Literal.of("service-name")   // signing service
).build();

// Build an endpoint with SigV4a authentication (multi-region)
List<Literal> regionSet = Arrays.asList(
    Literal.of("us-east-1"),
    Literal.of("us-west-2")
);

Endpoint sigv4aEndpoint = EndpointAuthUtils.sigv4a(
    Endpoint.builder().url("https://global-service.amazonaws.com"),
    regionSet,                   // signing region set
    Literal.of("global-service") // signing service
).build();

// Check if an auth scheme is SigV4 equivalent
boolean isSigV4 = EndpointAuthUtils.isSigV4EquivalentAuthScheme("sigv4");
boolean isSigV4Custom = EndpointAuthUtils.isSigV4EquivalentAuthScheme("sigv4-custom");
boolean isNotSigV4 = EndpointAuthUtils.isSigV4EquivalentAuthScheme("sigv4a");

Authentication Schemes

SigV4 Authentication

AWS Signature Version 4 (SigV4) is the standard signing process for AWS API requests.

Configuration Properties:

signingName: The service name for signing (e.g., "s3", "ec2")
signingRegion: The AWS region for signing (e.g., "us-east-1")

// SigV4 endpoint configuration
Map<String, Object> sigv4Config = Map.of(
    "signingName", "s3",
    "signingRegion", "us-east-1"
);

SigV4a Authentication

AWS Signature Version 4a (SigV4a) supports multi-region signing for global services.

Configuration Properties:

signingName: The service name for signing
signingRegionSet: Set of regions where the signature is valid

// SigV4a endpoint configuration
Map<String, Object> sigv4aConfig = Map.of(
    "signingName", "global-service",
    "signingRegionSet", Arrays.asList("us-east-1", "us-west-2", "eu-west-1")
);

SigV4 Sub-schemes

Special variants of SigV4 for specific services or use cases:

sigv4-s3express: Optimized signing for S3 Express One Zone
sigv4-custom: Custom signing variants

// Check for SigV4 sub-schemes
boolean isS3Express = EndpointAuthUtils.isSigV4EquivalentAuthScheme("sigv4-s3express");
boolean isCustomSigV4 = EndpointAuthUtils.isSigV4EquivalentAuthScheme("sigv4-custom");

Authentication Validation

Validation Rules

The validators enforce proper authentication configuration:

Required Properties: Signing name and region/region set must be specified
Type Validation: Properties must be correct types (string, array)
Value Validation: Regions must be valid AWS regions
Scheme Compatibility: Auth scheme must match endpoint configuration

Common Validation Errors

// Missing signing region
ValidationEvent error1 = ValidationEvent.builder()
    .severity(Severity.ERROR)
    .message("SigV4 authentication requires signingRegion property")
    .build();

// Invalid region format
ValidationEvent error2 = ValidationEvent.builder()
    .severity(Severity.ERROR) 
    .message("Invalid AWS region format: 'invalid-region'")
    .build();

// Empty signing region set for SigV4a
ValidationEvent error3 = ValidationEvent.builder()
    .severity(Severity.ERROR)
    .message("SigV4a authentication requires non-empty signingRegionSet")
    .build();

Integration with Built-ins

Authentication utilities work with AWS built-in parameters:

// Authentication-related built-ins
AwsBuiltIns.CREDENTIAL_SCOPE        // Credential scoping
AwsBuiltIns.ACCOUNT_ID              // Account-based signing
AwsBuiltIns.ACCOUNT_ID_ENDPOINT_MODE // Account endpoint mode

Best Practices

SigV4 Usage

// Standard SigV4 for regional services
EndpointAuthUtils.sigv4(
    builder,
    Literal.of("${Region}"),      // Use region parameter
    Literal.of("service-name")    // Service-specific signing name
);

SigV4a Usage

// SigV4a for global/multi-region services
EndpointAuthUtils.sigv4a(
    builder, 
    Arrays.asList(
        Literal.of("*")           // All regions
    ),
    Literal.of("global-service")
);

Scheme Detection

// Robust scheme detection
if (EndpointAuthUtils.isSigV4EquivalentAuthScheme(schemeName)) {
    // Handle as SigV4 (including sub-schemes)
} else if (EndpointAuthUtils.isSigV4AEquivalentAuthScheme(schemeName)) {
    // Handle as SigV4a
} else {
    // Handle other authentication schemes
}

Install with Tessl CLI

npx tessl i tessl/maven-software-amazon-smithy--smithy-aws-endpoints

docs

arn-parsing.md

authentication-utilities.md

aws-built-ins.md

aws-rule-set-extension.md

index.md

partition-resolution.md

s3-virtual-hosting.md

smithy-traits.md

validation-components.md

tile.json

tessl/maven-software-amazon-smithy--smithy-aws-endpoints