auth/docs/getting-started/AWS_SSM_SETUP.md

AWS Systems Manager (SSM) Parameter Store Setup

This guide explains how to configure the auth service to use AWS Systems Manager Parameter Store for database credentials.

Overview

Instead of storing database credentials in environment variables, you can store them securely in AWS SSM Parameter Store. The service will automatically fetch credentials from SSM when enabled.

Prerequisites

1. AWS Account with SSM Parameter Store access
2. Database credentials stored in SSM Parameter Store
3. AWS credentials configured (IAM role, environment variables, or credentials file)

SSM Parameter Structure

Store your database credentials as a JSON string in SSM Parameter Store:

Parameter Path:

• Test/Development: /test/livingai/db/app
• Production: /prod/livingai/db/app

Parameter Value (JSON):

{
  "user": "read_write_user",
  "password": "your_password_here",
  "host": "db.livingai.app",
  "dbname": "livingai_test_db"
}

Parameter Type: SecureString (encrypted)

Configuration

1. Environment Variables

Add these to your .env file or environment:

# Enable AWS SSM integration
USE_AWS_SSM=true

# AWS Region (default: ap-south-1)
AWS_REGION=ap-south-1

# Optional: Explicit AWS credentials (only for local/testing)
# In production, use IAM roles instead
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key

2. AWS Credentials Setup

Option A: IAM Role (Recommended for EC2/ECS/Lambda)

• Attach an IAM role to your EC2 instance, ECS task, or Lambda function
• The role should have permission to access SSM Parameter Store

Required IAM Policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter",
        "ssm:GetParameters"
      ],
      "Resource": [
        "arn:aws:ssm:ap-south-1:*:parameter/test/livingai/db/*",
        "arn:aws:ssm:ap-south-1:*:parameter/prod/livingai/db/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": "arn:aws:kms:ap-south-1:*:key/*"
    }
  ]
}

Option B: Environment Variables (Local/Testing)

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=ap-south-1

Option C: AWS Credentials File

aws configure

3. Fallback to DATABASE_URL

If SSM is not available or USE_AWS_SSM is not set, the service will fall back to using DATABASE_URL from environment variables. This is useful for:

• Local development
• Testing environments without AWS access
• Backward compatibility

Environment Detection

The service automatically selects the correct parameter path based on NODE_ENV:

• NODE_ENV=production or NODE_ENV=prod → /prod/livingai/db/app
• Any other value (including test, development, etc.) → /test/livingai/db/app

You can also override this by setting the environment explicitly in code.

Usage

Enable SSM Integration

USE_AWS_SSM=true
AWS_REGION=ap-south-1

Disable SSM (Use DATABASE_URL)

USE_AWS_SSM=false
# or simply don't set it
DATABASE_URL=postgresql://user:password@host:5432/dbname

Testing

1. Test SSM Connection:

   # Set environment variables
   export USE_AWS_SSM=true
   export AWS_REGION=ap-south-1
   
   # Start the service
   npm start
   

2. Check Logs:

   • Success: ✅ Successfully fetched DB credentials from SSM: /test/livingai/db/app
   • Fallback: ⚠️ AWS SSM not available, falling back to DATABASE_URL

Troubleshooting

Error: "Failed to fetch DB credentials from SSM"

Possible causes:

1. Missing IAM permissions - Check IAM role/policy
2. Wrong parameter path - Verify parameter exists in SSM console
3. Wrong region - Ensure AWS_REGION matches parameter region
4. Invalid credentials - Check AWS credentials configuration

Solution:

• Verify parameter exists: aws ssm get-parameter --name "/test/livingai/db/app" --with-decryption
• Check IAM permissions
• Verify AWS credentials are configured correctly

Error: "UnrecognizedClientException"

Cause: AWS SDK cannot find credentials

Solution:

• Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY for local testing
• Or configure IAM role for AWS services

Service Falls Back to DATABASE_URL

Cause: SSM not available or not enabled

Solution:

• This is expected behavior for local development
• Ensure USE_AWS_SSM=true is set
• Verify AWS credentials are configured

Security Best Practices

1. Never commit AWS credentials to version control
2. Use IAM roles in production (not access keys)
3. Store parameters as SecureString (encrypted)
4. Use least privilege IAM policies
5. Rotate credentials regularly
6. Monitor SSM access in CloudTrail

Migration from DATABASE_URL

1. Store credentials in SSM Parameter Store
2. Set USE_AWS_SSM=true
3. Remove DATABASE_URL from environment (optional, service will ignore it)
4. Restart the service

The service will automatically use SSM credentials when available.