How-To Guide

How to Use AWS Secrets Manager

Managed secrets storage with automatic rotation

TL;DR

TL;DR (15 minutes): Create a secret in AWS Secrets Manager console, grant IAM access to your app, then use the AWS SDK to retrieve secrets at runtime. Secrets Manager handles encryption, versioning, and optional automatic rotation.

Prerequisites:

AWS account with admin access
AWS CLI configured locally
Basic understanding of IAM roles

Why This Matters

AWS Secrets Manager is a fully managed service that eliminates the need to hardcode credentials in your application. It encrypts secrets at rest using KMS, provides automatic rotation for supported databases, and integrates seamlessly with other AWS services.

Compared to storing secrets in environment variables or config files, Secrets Manager provides audit logging, fine-grained access control, and versioning - essential for compliance and incident response.

Step-by-Step Guide

Create a secret in AWS Console

Navigate to AWS Secrets Manager and click "Store a new secret":

Go to AWS Console → Secrets Manager
Click "Store a new secret"
Choose "Other type of secret" for API keys/custom secrets
Or choose "Credentials for Amazon RDS database" for database passwords

Configure your secret values

Add your key-value pairs:

# Example secret structure
{
  "STRIPE_SECRET_KEY": "sk_live_xxxxx",
  "OPENAI_API_KEY": "sk-xxxxx",
  "DATABASE_URL": "postgresql://user:pass@host:5432/db"
}

Give your secret a meaningful name like myapp/production/api-keys. The path-like naming helps organize secrets across environments.

Set up IAM permissions

Create an IAM policy that allows your application to read the secret:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": [
        "arn:aws:secretsmanager:us-east-1:123456789:secret:myapp/production/*"
      ]
    }
  ]
}

Attach this policy to your Lambda function's role, EC2 instance profile, or ECS task role.

Retrieve secrets in your application

Use the AWS SDK to fetch secrets at runtime:

// Node.js
import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";

const client = new SecretsManagerClient({ region: "us-east-1" });

async function getSecrets() {
  const command = new GetSecretValueCommand({
    SecretId: "myapp/production/api-keys"
  });

  const response = await client.send(command);
  return JSON.parse(response.SecretString);
}

// Use in your app
const secrets = await getSecrets();
const stripe = new Stripe(secrets.STRIPE_SECRET_KEY);

Cache secrets for performance

Avoid calling Secrets Manager on every request - cache secrets:

// Cache secrets with TTL
let cachedSecrets = null;
let cacheExpiry = 0;
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedSecrets() {
  if (cachedSecrets && Date.now() < cacheExpiry) {
    return cachedSecrets;
  }

  cachedSecrets = await getSecrets();
  cacheExpiry = Date.now() + CACHE_TTL;
  return cachedSecrets;
}

AWS also provides the Secrets Manager caching library for production use.

Enable automatic rotation (optional)

For RDS databases, Secrets Manager can automatically rotate credentials:

In the secret configuration, click "Edit rotation"
Enable automatic rotation
Choose a rotation schedule (e.g., every 30 days)
Select the Lambda rotation function (AWS provides built-in ones for RDS)

Cost Considerations:

AWS Secrets Manager costs $0.40/secret/month plus $0.05 per 10,000 API calls. For apps with many secrets, consider grouping related secrets into single entries to reduce costs.

How to Verify It Worked

CLI test: Run aws secretsmanager get-secret-value --secret-id myapp/production/api-keys
Check CloudTrail: Verify access attempts are being logged
Test IAM permissions: Ensure only authorized roles can retrieve secrets
Application test: Deploy and verify your app successfully retrieves secrets

# Test from CLI
aws secretsmanager get-secret-value \
  --secret-id myapp/production/api-keys \
  --query SecretString --output text | jq

# List all secrets
aws secretsmanager list-secrets

Common Errors & Troubleshooting

Error: "AccessDeniedException"

Your IAM role doesn't have permission. Check the policy is attached and the resource ARN matches your secret.

Error: "ResourceNotFoundException"

Secret doesn't exist or you're in the wrong region. Verify the secret name and region match.

Error: "DecryptionFailure"

KMS key access issue. Ensure your role has kms:Decrypt permission for the secret's encryption key.

High API costs

You're calling GetSecretValue too often. Implement caching to reduce API calls.

Secrets Manager vs. Parameter Store - which should I use?

Use Secrets Manager for sensitive credentials that need rotation, auditing, or cross-account access. Use Parameter Store (free tier) for non-sensitive configuration. Secrets Manager is more expensive but purpose-built for secrets.

How do I use Secrets Manager with Lambda?

Add the IAM policy to your Lambda execution role. For better cold-start performance, use the AWS Parameters and Secrets Lambda Extension which caches secrets locally.

Can I access secrets across AWS accounts?

Yes, using resource-based policies. Add a policy to the secret that allows the other account's role to access it, then assume that role or use direct cross-account access.