Secrets Manager

# ===== What it is =====
# Managed service for storing secrets (DB credentials, API keys, OAuth tokens).
# Versioned, encrypted via KMS, accessed via IAM, optionally rotated automatically.

# Compared to Systems Manager Parameter Store:
# - Secrets Manager: rotation, cross-account, native RDS integration, higher cost
# - Parameter Store: free for standard params, cheaper for large config sets

# ===== Create a secret =====
aws secretsmanager create-secret \
  --name prod/db/password \
  --secret-string '{"username":"app","password":"..."}' \
  --kms-key-id alias/my-app-key

# Or via console / CDK / Terraform.

# ===== Retrieve =====
aws secretsmanager get-secret-value --secret-id prod/db/password
# {
#   "Name": "prod/db/password",
#   "SecretString": "{...}",
#   "VersionId": "...",
#   "VersionStages": ["AWSCURRENT"]
# }

# In code (Node):
import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
const sm = new SecretsManagerClient({});
const r = await sm.send(new GetSecretValueCommand({ SecretId: 'prod/db/password' }));
const creds = JSON.parse(r.SecretString);

# Python (boto3):
import boto3, json
sm = boto3.client('secretsmanager')
r = sm.get_secret_value(SecretId='prod/db/password')
creds = json.loads(r['SecretString'])

# ===== Caching (important for cost + latency) =====
# Use the AWS Secrets Manager caching libraries:
# Node: @aws-sdk/util-cache
# Python: aws-secretsmanager-caching
# Java: aws-secretsmanager-caching-java

# Defaults: refresh every hour. Configurable.

# ===== Rotation =====
# 1. Native (RDS / Aurora / DocumentDB / Redshift): one-click rotation
# 2. Custom: Lambda function with hooks (createSecret, setSecret, testSecret, finishSecret)
# 3. Disabled: manual rotation only

# Enable native rotation:
aws secretsmanager rotate-secret \
  --secret-id prod/db/password \
  --rotation-lambda-arn arn:aws:lambda:...:function:SecretsManagerRDSPostgreSQLRotationSingleUser \
  --rotation-rules AutomaticallyAfterDays=30

# ===== IAM =====
# Grant least-privilege access; restrict by ResourcePolicies on the secret:
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["secretsmanager:GetSecretValue"],
    "Resource": "arn:aws:secretsmanager:ap-southeast-2:123:secret:prod/db/password-*"
  }]
}

# Pair with KMS key permissions; granting GetSecretValue isn't enough if user can't Decrypt the KMS key.

# ===== Cross-account =====
# Resource policy on the secret + KMS key policy + IAM principal in the consumer account.

# ===== Cost =====
# - USD 0.40/month per secret
# - USD 0.05 per 10,000 API calls
# Cache responses to keep API calls low.

# ===== Patterns =====
# - Naming: env/service/resource (prod/shop/db, dev/api/jwt-key)
# - One secret per credential rotation unit
# - KMS CMK per environment for compliance
# - Cache in-process; refresh on TTL
# - Rotation: 30-90 days for DB passwords; 365 for long-lived API keys
# - Audit access via CloudTrail (Secrets Manager events visible)

# ===== Pitfalls =====
# - Plain-text in environment variables instead of fetching at boot
# - No rotation -> stale credentials
# - Wide IAM (secretsmanager:* on Resource: *)
# - KMS Decrypt forgotten -> 'cannot decrypt' errors
# - Calling GetSecretValue per request -> rate limits + cost

# Store + rotate database creds, API keys, JWT signers.