Vaultx.Auth.AWS (Vaultx v0.7.0)

View Source

AWS authentication method for HashiCorp Vault.

This module implements comprehensive AWS authentication for Vault, supporting both EC2 instance-based and IAM principal-based authentication. It provides secure, scalable authentication for AWS workloads with full support for cross-account scenarios and advanced AWS features.

AWS Authentication Types

EC2 Instance Authentication

  • Instance Identity: Uses EC2 instance identity documents
  • Role Tags: Supports EC2 role tag-based authentication
  • PKCS7 Signatures: Validates instance identity signatures
  • Nonce Support: Prevents replay attacks

IAM Authentication

  • IAM Principals: Authenticates IAM users and roles
  • STS Integration: Uses AWS Security Token Service
  • Cross-Account: Supports cross-account role assumption
  • Request Signing: AWS Signature Version 4 support

Advanced Features

  • Multi-Region: Works across all AWS regions
  • Auto-Discovery: Automatic instance metadata detection
  • Security: Built-in replay attack prevention
  • Flexibility: Configurable authentication parameters

API Compliance

Fully implements HashiCorp Vault AWS authentication:

EC2 instances can authenticate using their instance identity document:

{:ok, auth_response} = Vaultx.Auth.AWS.authenticate(%{
  role: "my-ec2-role"
})

IAM Authentication

IAM principals authenticate using signed STS GetCallerIdentity requests:

# Manual IAM authentication with pre-signed request
{:ok, auth_response} = Vaultx.Auth.AWS.authenticate(%{
  role: "my-iam-role",
  iam_http_request_method: "POST",
  iam_request_url: "https://sts.amazonaws.com/",
  iam_request_body: "Action=GetCallerIdentity&Version=2011-06-15",
  iam_request_headers: "Authorization: AWS4-HMAC-SHA256 ..."
})

Additional Options

# With server ID header for additional security
{:ok, auth_response} = Vaultx.Auth.AWS.authenticate(%{
  role: "my-role",
  server_id: "vault.example.com"
})

# With nonce for EC2 authentication
{:ok, auth_response} = Vaultx.Auth.AWS.authenticate(%{
  role: "my-role",
  nonce: "unique-nonce-value"
})

# With role tag for EC2 authentication
{:ok, auth_response} = Vaultx.Auth.AWS.authenticate(%{
  role: "my-role",
  role_tag: "v1:09V0qGuyB8=:a=ami-fce3c696:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/"
})

Vault Configuration

Before using this authentication method, configure it in Vault:

# Enable AWS auth method
vault auth enable aws

# Configure AWS credentials (optional for EC2-based Vault)
vault write auth/aws/config/client \
  access_key="AKIA..." \
  secret_key="..." \
  region="us-east-1"

# Create EC2 role
vault write auth/aws/role/my-ec2-role \
  auth_type=ec2 \
  bound_ami_id=ami-12345678 \
  policies=my-policy \
  max_ttl=500h

# Create IAM role
vault write auth/aws/role/my-iam-role \
  auth_type=iam \
  bound_iam_principal_arn="arn:aws:iam::123456789012:role/MyRole" \
  policies=my-policy \
  max_ttl=1h

Security Considerations

  • Use IAM roles instead of IAM users when possible
  • Implement proper IAM policies with least privilege
  • Monitor authentication events in Vault audit logs
  • Use bound conditions to restrict access appropriately
  • Configure server ID header for additional security
  • Regularly review and rotate AWS credentials