alanyeung-s3/aws

AWS STS Mock Server

A Go-based mock implementation of AWS Security Token Service (STS) with AWS Signature Version 4 (SigV4) authentication.

Features

• ✅ Full AWS Signature Version 4 (SigV4) validation
• ✅ STS GetCallerIdentity API implementation
• ✅ Configurable SigV4 validation per endpoint
• ✅ Comprehensive error handling matching AWS STS behavior
• ✅ Compatible with AWS CLI and SDKs
• ✅ Extensive test coverage

Architecture

aws-sts-mock/
├── main.go                    # HTTP server and request routing
├── pkg/
│   ├── sigv4/
│   │   ├── sigv4.go          # SigV4 validation middleware
│   │   └── sigv4_test.go     # SigV4 validation tests
│   └── sts/
│       └── types.go          # STS response types
├── main_test.go              # Integration tests
├── Makefile                  # Build and test commands
└── README.md                 # This file

Prerequisites

• Go 1.21 or higher
• AWS CLI (for testing)

Installation

# Clone or create the project
cd aws-sts-mock

# Install dependencies
make install-deps

# Build the project
make build

Usage

Starting the Server

# Using make
make run

# Or directly with go
go run main.go

# Or with custom port
PORT=8080 go run main.go

The server will start on port 8080 by default.

Available Endpoints

1. STS GetCallerIdentity (with SigV4 validation)

• Method: POST
• Path: /
• Authentication: AWS SigV4 required
• Parameters:
  • Action=GetCallerIdentity
  • Version=2011-06-15

2. Health Check (no authentication)

• Method: GET
• Path: /health
• Authentication: None

Testing with AWS CLI

Configure AWS CLI

# Set up credentials (use the mock credentials)
export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
export AWS_DEFAULT_REGION="us-east-1"

Test the Mock Server

# Start the server in one terminal
make run

# In another terminal, test with AWS CLI
aws sts get-caller-identity \
  --endpoint-url http://localhost:8080 \
  --no-verify-ssl

# Expected output:
# {
#     "UserId": "123456789012",
#     "Account": "123456789012",
#     "Arn": "arn:aws:iam::123456789012:root"
# }

Testing with Session Token

# Use credentials with session token
export AWS_ACCESS_KEY_ID="ASIAUIJXACK3L66H7KB4"
export AWS_SECRET_ACCESS_KEY="test-secret-key"
export AWS_SESSION_TOKEN="test-session-token"

aws sts get-caller-identity \
  --endpoint-url http://localhost:8080 \
  --no-verify-ssl

Running Tests

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific package tests
go test -v ./pkg/sigv4/
go test -v ./pkg/sts/

SigV4 Validation

The server implements complete AWS Signature Version 4 validation:

Validated Components

1. Authorization Header

   • Algorithm (AWS4-HMAC-SHA256)
   • Credential (AccessKeyID, date, region, service)
   • SignedHeaders
   • Signature

2. Request Timestamp

   • X-Amz-Date header presence
   • Request within 15-minute window
   • Future request rejection

3. Signature Calculation

   • Canonical request creation
   • String to sign generation
   • Signing key derivation
   • HMAC-SHA256 signature

4. Credential Validation

   • Access key ID verification
   • Secret access key matching
   • Session token validation (when present)

Error Responses

The server returns standard AWS STS error responses:

• MissingAuthenticationToken - No Authorization header
• InvalidClientTokenId - Invalid access key
• SignatureDoesNotMatch - Signature validation failed
• RequestExpired - Request timestamp expired
• InvalidRequest - Malformed request
• AccessDenied - Permission denied

Mock Credentials

The server includes two mock credential sets for testing:

Credential Set 1 (Long-term IAM user)

AccessKeyID: AKIAIOSFODNN7EXAMPLE
SecretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AccountID: 123456789012

Credential Set 2 (Temporary with session token)

AccessKeyID: ASIAUIJXACK3L66H7KB4
SecretAccessKey: test-secret-key
SessionToken: test-session-token
AccountID: 292709995190

Configuration

Disabling SigV4 for Specific Endpoints

To disable SigV4 validation for an endpoint, simply don't wrap it with the middleware:

// With SigV4 validation
mux.HandleFunc("POST /", sigv4.ValidateSigV4Middleware(handleSTSRequest))

// Without SigV4 validation
mux.HandleFunc("GET /health", handleHealth)

Adding New Mock Credentials

Edit pkg/sigv4/sigv4.go and add to the mockCredentials map:

var mockCredentials = map[string]AWSCredentials{
    "YOUR_ACCESS_KEY_ID": {
        AccessKeyID:     "YOUR_ACCESS_KEY_ID",
        SecretAccessKey: "YOUR_SECRET_KEY",
        SessionToken:    "OPTIONAL_SESSION_TOKEN",
        AccountID:       "YOUR_ACCOUNT_ID",
    },
}

Development

Project Structure

• main.go - HTTP server, routing, and STS request handling
• pkg/sigv4/ - SigV4 authentication middleware
• pkg/sts/ - STS response type definitions
• *_test.go - Unit and integration tests

Adding New STS Operations

1. Add operation to handleSTSRequest() switch statement
2. Implement handler function
3. Add response types to pkg/sts/types.go
4. Add tests to main_test.go

Example:

case "AssumeRole":
    handleAssumeRole(w, r)

Code Quality

# Format code
make fmt

# Run linter
make vet

# Run both
make lint

Testing Signature Validation

The project includes comprehensive tests for signature validation:

# Test valid signatures
go test -v -run TestValidateSigV4Middleware/Valid ./pkg/sigv4/

# Test expired requests
go test -v -run TestValidateSigV4Middleware/Expired ./pkg/sigv4/

# Test invalid signatures
go test -v -run TestValidateSigV4Middleware/Invalid ./pkg/sigv4/

Troubleshooting

"SignatureDoesNotMatch" Error

1. Verify credentials match exactly
2. Check system clock synchronization
3. Ensure proper URL encoding
4. Verify canonical request construction

Request Expired

1. Check system time is accurate
2. Verify NTP synchronization
3. Request must be within 15 minutes of current time

Invalid Credentials

1. Verify AccessKeyID exists in mock credentials
2. Check SecretAccessKey matches
3. For temporary credentials, verify SessionToken

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License

References

• AWS Signature Version 4
• AWS STS API Reference
• Troubleshooting Signature Errors