Eve library

Oshun Secrets Management Module

Other

Revision 1

On this page

This Terraform module manages secrets in AWS Secrets Manager for all Oshun services across domains.

Features#

  • Centralized Secrets Management: All application secrets stored in AWS Secrets Manager
  • KMS Encryption: Dedicated KMS key for secrets encryption with key rotation
  • Automatic Password Generation: Generate strong passwords for databases and services
  • Secret Rotation: Lambda-based automatic rotation for database credentials and tokens
  • Multi-Region Replication: Replicate secrets across regions for disaster recovery
  • ECS Integration: Pre-formatted outputs for ECS task definition secrets blocks
  • Domain Isolation: Organized secrets by domain (database, redis, jwt, encryption, oauth, ai, external)

Usage#

hcl
module "secrets" {
  source = "../secrets"

  environment = "production"
  region      = "us-east-1"
  name_prefix = "oshun"

  # KMS Configuration
  create_kms_key          = true
  kms_key_deletion_window = 30

  # Multi-region replication
  replica_regions = ["us-west-2"]

  # Database secrets
  database_secrets = {
    main = {
      description       = "Main database credentials"
      database          = "oshun"
      username          = "oshun_app"
      host              = module.rds.endpoint
      port              = 5432
      generate_password = true
      rotation_days     = 30
    }
  }

  # JWT secrets
  jwt_secrets = {
    access = {
      description     = "JWT access token secret"
      generate_secret = true
      length          = 64
      rotation_days   = 90
    }
  }

  # AI provider secrets
  ai_provider_secrets = {
    openai = {
      description = "OpenAI API credentials"
      api_key     = var.openai_api_key
      org_id      = var.openai_org_id
    }
  }

  # Rotation configuration
  enable_database_rotation = true
  rotation_vpc_id          = module.vpc.vpc_id
  rotation_subnet_ids      = module.vpc.private_subnet_ids
  psycopg2_layer_path      = "lambda-layers/psycopg2.zip"

  tags = {
    Environment = "production"
  }
}

Secret Types#

Database Secrets#

Stores credentials for PostgreSQL databases with connection string generation.

hcl
database_secrets = {
  main = {
    description       = "Main database credentials"
    database          = "oshun"
    username          = "oshun_app"
    host              = "db.example.com"
    port              = 5432
    engine            = "postgres"
    generate_password = true
    rotation_days     = 30  # 0 to disable rotation
  }
}

Secret structure:

json
{
  "username": "oshun_app",
  "password": "generated-password",
  "host": "db.example.com",
  "port": 5432,
  "database": "oshun",
  "engine": "postgres",
  "connection_string": "postgresql://oshun_app:password@db.example.com:5432/oshun"
}

Redis Secrets#

Stores Redis/ElastiCache authentication tokens.

hcl
redis_secrets = {
  main = {
    description       = "Main Redis credentials"
    generate_password = true
  }
}

JWT Secrets#

Stores JWT signing secrets for token generation.

hcl
jwt_secrets = {
  access = {
    description     = "JWT access token secret"
    generate_secret = true
    length          = 64
    rotation_days   = 90
  }
}

Encryption Keys#

Stores application-level encryption keys.

hcl
encryption_keys = {
  data = {
    description   = "Data encryption key"
    generate_key  = true
    length        = 32
    rotation_days = 365
  }
}

OAuth Secrets#

Stores OAuth provider credentials.

hcl
oauth_secrets = {
  google = {
    description   = "Google OAuth credentials"
    client_id     = "your-client-id"
    client_secret = "your-client-secret"
  }
}

AI Provider Secrets#

Stores AI service API keys.

hcl
ai_provider_secrets = {
  openai = {
    description = "OpenAI API credentials"
    api_key     = "sk-..."
    org_id      = "org-..."
  }
}

External Service Secrets#

Stores credentials for external services.

hcl
external_service_secrets = {
  stripe = {
    description    = "Stripe credentials"
    api_key        = "pk_..."
    secret_key     = "sk_..."
    webhook_secret = "whsec_..."
  }
}

Storage Secrets#

Stores S3-compatible storage credentials.

hcl
storage_secrets = {
  s3 = {
    description   = "S3 storage credentials"
    access_key    = ""
    secret_key    = ""
    generate_keys = true
  }
}

Custom Secrets#

Stores arbitrary secrets with flexible structure.

hcl
custom_secrets = {
  internal-keys = {
    description   = "Internal service keys"
    secret_string = ""  # Raw string, or use secret_data for JSON
    secret_data = {
      key1 = "value1"
      key2 = "value2"
    }
  }
}

Outputs#

Secret ARNs#

hcl
# Individual secret ARNs
module.secrets.database_secret_arns["main"]
module.secrets.jwt_secret_arns["access"]
module.secrets.ai_provider_secret_arns["openai"]

# Convenience outputs for domain databases
module.secrets.main_database_secret_arn
module.secrets.yemaya_database_secret_arn
module.secrets.lilith_database_secret_arn

ECS Integration#

Pre-formatted outputs for ECS task definitions:

hcl
# Database connection strings
module.secrets.ecs_database_secrets["main"]
# => { name = "MAIN_DATABASE_URL", valueFrom = "arn:...:connection_string::" }

# JWT secrets
module.secrets.ecs_jwt_secrets["access"]
# => { name = "JWT_ACCESS_SECRET", valueFrom = "arn:...:secret::" }

IAM Policy#

Ready-to-use IAM policy for secret access:

hcl
resource "aws_iam_role_policy" "secrets_access" {
  role   = aws_iam_role.task.id
  policy = module.secrets.secrets_read_policy_json
}

Secret Rotation#

Database Rotation#

When rotation_days > 0, a Lambda function is created to automatically rotate database passwords:

  1. createSecret: Generates new password and stores as AWSPENDING version
  2. setSecret: Connects to database and updates the user's password
  3. testSecret: Verifies the new password works
  4. finishSecret: Promotes AWSPENDING to AWSCURRENT

Requirements:

  • rotation_vpc_id: VPC where Lambda will run
  • rotation_subnet_ids: Private subnets with database connectivity
  • psycopg2_layer_path: Path to Lambda layer with psycopg2

JWT/Encryption Key Rotation#

Self-contained rotation that generates new keys without external dependencies:

  1. Generates new random secret of the same length
  2. Stores as AWSPENDING version
  3. Promotes to AWSCURRENT after verification

Note: Applications should support both current and pending versions during rotation window.

Accessing Secrets in Applications#

ECS Task Definition#

hcl
resource "aws_ecs_task_definition" "app" {
  container_definitions = jsonencode([{
    name = "app"
    secrets = [
      {
        name      = "DATABASE_URL"
        valueFrom = "${module.secrets.database_secret_arns["main"]}:connection_string::"
      },
      {
        name      = "JWT_SECRET"
        valueFrom = "${module.secrets.jwt_secret_arns["access"]}:secret::"
      },
      {
        name      = "OPENAI_API_KEY"
        valueFrom = "${module.secrets.ai_provider_secret_arns["openai"]}:api_key::"
      }
    ]
  }])
}

Application Code (Node.js)#

typescript
import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from '@aws-sdk/client-secrets-manager';

const client = new SecretsManagerClient({});

async function getSecret(secretArn: string): Promise<Record<string, unknown>> {
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: secretArn })
  );
  return JSON.parse(response.SecretString!);
}

// Get database credentials
const dbSecret = await getSecret(process.env.DATABASE_SECRET_ARN!);
const connectionString = dbSecret.connection_string;

Security Best Practices#

  1. Least Privilege: Use the generated IAM policy and scope to only needed secrets
  2. KMS Key Policies: Restrict KMS key access to authorized services
  3. VPC Endpoints: Use Secrets Manager VPC endpoints to avoid public internet
  4. Rotation: Enable rotation for all credentials, especially databases
  5. Audit Logging: Enable CloudTrail logging for secret access
  6. Recovery Window: Use appropriate recovery windows (30 days for production)

Inputs#

Name Description Type Default Required
environment Deployment environment string - yes
region AWS region string "us-east-1" no
name_prefix Prefix for secret names string "oshun" no
create_kms_key Create dedicated KMS key bool true no
kms_key_arn Existing KMS key ARN string "" no
replica_regions Regions for secret replication list(string) [] no
database_secrets Database credentials map map(object) {} no
redis_secrets Redis credentials map map(object) {} no
jwt_secrets JWT secrets map map(object) {} no
encryption_keys Encryption keys map map(object) {} no
oauth_secrets OAuth provider secrets map map(object) {} no
ai_provider_secrets AI provider API keys map map(object) {} no
external_service_secrets External service secrets map map(object) {} no
storage_secrets Storage credentials map map(object) {} no
custom_secrets Custom secrets map map(object) {} no
recovery_window_in_days Days before permanent deletion number 7 no
enable_database_rotation Enable database rotation bool false no
rotation_vpc_id VPC for rotation Lambda string "" no
rotation_subnet_ids Subnets for rotation Lambda list(string) [] no
psycopg2_layer_path Path to psycopg2 Lambda layer string "" no

Outputs#

Name Description
kms_key_arn ARN of the KMS key
database_secret_arns Map of database secret ARNs
redis_secret_arns Map of Redis secret ARNs
jwt_secret_arns Map of JWT secret ARNs
encryption_key_arns Map of encryption key ARNs
oauth_secret_arns Map of OAuth secret ARNs
ai_provider_secret_arns Map of AI provider secret ARNs
external_service_secret_arns Map of external service secret ARNs
storage_secret_arns Map of storage secret ARNs
custom_secret_arns Map of custom secret ARNs
all_secret_arns Combined map of all secret ARNs
secrets_read_policy_json IAM policy JSON for secret access
ecs_database_secrets ECS-formatted database secrets
ecs_jwt_secrets ECS-formatted JWT secrets
secrets_summary Summary of all created secrets