AWS Secrets Manager Rotation: How Automatic Secret Rotation Works

Simple explanation

In technical terms, when rotation runs it generates a new password, updates the database (or API, or whatever service uses the credential), verifies the new password works, and then promotes it to the active version. The old password stays available briefly so applications mid-request do not break.

A real example: your production app uses a PostgreSQL password stored in Secrets Manager. Every 30 days, rotation generates a new password, runs an ALTER USER command on the database, confirms the connection works, and promotes the new password to active. Your app fetches the latest password on its next connection attempt.

When to use automatic rotation

Managed rotation vs Lambda rotation

Secrets Manager offers two rotation approaches. Understanding the difference prevents you from over-engineering simple cases or under-building complex ones.

Managed rotation is available for supported AWS database services (RDS, Redshift, DocumentDB). AWS handles the entire rotation process internally. You do not create, deploy, or manage a Lambda function.

Lambda-based rotation is used for everything else, and also when you need custom rotation logic for database secrets (for example, a multi-step credential change that involves external systems). You write a Lambda function that implements the four rotation steps, and Secrets Manager invokes it on schedule.

How Secrets Manager rotation works

Regardless of whether you use managed or Lambda-based rotation, the internal process follows four steps. Understanding these steps helps you debug rotation failures.

Version staging labels

Every secret version in Secrets Manager carries a staging label that tracks where it sits in the rotation lifecycle:

The four rotation steps

If any step fails, the rotation stops and AWSCURRENT remains unchanged. Your application continues using the existing credential. You can monitor failures through CloudTrail events and CloudWatch Logs.

How to set up rotation for RDS, Redshift, and DocumentDB

For supported database services, the setup depends on whether you use managed rotation (recommended) or Lambda-based rotation.

Managed rotation (console)

1. Open the secret in the Secrets Manager console.
2. Choose Set up automatic rotation.
3. Select a rotation schedule (for example, every 30 days).
4. Choose a rotation strategy: single user (updates the same database user) or alternating users (switches between two database users, keeping one active at all times).
5. Save. Secrets Manager provisions the rotation infrastructure automatically.

Managed rotation (CLI)

# Enable managed rotation for an RDS secret (no Lambda ARN needed)
aws secretsmanager rotate-secret \
  --secret-id "prod/myapp/postgres" \
  --rotation-rules '{"ScheduleExpression":"rate(30 days)","Duration":"2h"}'

Notice there is no —rotation-lambda-arn parameter. For managed rotation, Secrets Manager handles the rotation function internally.

Lambda-based rotation for databases (when you need custom logic)

If you need custom behavior during rotation, such as notifying an external system or performing additional validation, you can create your own Lambda function and pass its ARN:

# Enable rotation with a custom Lambda function
aws secretsmanager rotate-secret \
  --secret-id "prod/myapp/postgres" \
  --rotation-lambda-arn arn:aws:lambda:us-east-1:123456789012:function:MyCustomRotation \
  --rotation-rules '{"ScheduleExpression":"rate(30 days)","Duration":"2h"}'

Prerequisites

Before rotation will work, verify these requirements:

• Network access. The rotation process (whether managed or Lambda) must be able to reach the database. For databases in a VPC, this means the rotation infrastructure needs to be in the same VPC or have routing to it.
• Secrets Manager API access. If rotation runs inside a private VPC subnet with no internet access, create a VPC endpoint for Secrets Manager or configure a NAT gateway so the rotation process can call the Secrets Manager API.
• IAM permissions. The rotation process needs secretsmanager:GetSecretValue, secretsmanager:PutSecretValue, secretsmanager:UpdateSecretVersionStage, and secretsmanager:DescribeSecret on the secret.
• KMS access. If the secret is encrypted with a customer managed key (CMK), the rotation process also needs kms:Decrypt and kms:GenerateDataKey permissions on that key.
• Database permissions. The database user whose credentials are stored in the secret must have permission to change its own password (for single-user rotation) or create and manage the alternating user (for alternating-users rotation).

How to set up rotation for custom secrets

For API keys, OAuth tokens, or any credential not covered by managed rotation, you write a Lambda function that implements the four rotation steps. Secrets Manager invokes your function with these event fields:

• SecretId is the ARN of the secret being rotated.
• ClientRequestToken is a unique ID for this rotation attempt. It becomes the new version ID.
• Step is one of createSecret, setSecret, testSecret, or finishSecret.

Here is a minimal Lambda structure showing the control flow:

import boto3
import json

def lambda_handler(event, context):
    client = boto3.client('secretsmanager')
    arn = event['SecretId']
    token = event['ClientRequestToken']
    step = event['Step']

    if step == "createSecret":
        # Generate new credentials and store as AWSPENDING
        current = json.loads(
            client.get_secret_value(SecretId=arn)['SecretString']
        )
        current['api_key'] = generate_new_api_key()
        client.put_secret_value(
            SecretId=arn,
            ClientRequestToken=token,
            SecretString=json.dumps(current),
            VersionStages=['AWSPENDING']
        )
    elif step == "setSecret":
        # Call the external API to register the new key
        pending = json.loads(
            client.get_secret_value(
                SecretId=arn, VersionId=token, VersionStage='AWSPENDING'
            )['SecretString']
        )
        register_key_with_provider(pending['api_key'])
    elif step == "testSecret":
        # Verify the new key works
        pending = json.loads(
            client.get_secret_value(
                SecretId=arn, VersionId=token, VersionStage='AWSPENDING'
            )['SecretString']
        )
        call_provider_api(pending['api_key'])
    elif step == "finishSecret":
        # Promote AWSPENDING to AWSCURRENT
        metadata = client.describe_secret(SecretId=arn)
        current_version = next(
            v for v, stages in metadata['VersionIdsToStages'].items()
            if 'AWSCURRENT' in stages
        )
        client.update_secret_version_stage(
            SecretId=arn, VersionStage='AWSCURRENT',
            MoveToVersionId=token, RemoveFromVersionId=current_version
        )

Testing custom rotation safely

1. Start with a secret that points to a test or staging environment.
2. Trigger rotation manually: aws secretsmanager rotate-secret —secret-id “test/myapp/api-key”
3. Check CloudWatch Logs for the Lambda to verify each step completed.
4. Confirm the AWSCURRENT version has the new credential: aws secretsmanager get-secret-value —secret-id “test/myapp/api-key”
5. Verify your application can still authenticate using the secret.

Rotation schedules and windows

rate() expressions

The simplest option. Rotation runs at a fixed interval from the last rotation.

# Rotate every 30 days
aws secretsmanager rotate-secret \
  --secret-id "prod/myapp/database" \
  --rotation-rules '{"ScheduleExpression":"rate(30 days)"}'

cron() expressions

For precise timing, use a cron expression. All cron schedules run in UTC.

# Rotate at 2:00 AM UTC on the first Sunday of every month
aws secretsmanager rotate-secret \
  --secret-id "prod/myapp/database" \
  --rotation-rules '{"ScheduleExpression":"cron(0 2 ? * SUN#1 *)"}'

Rotation windows

The Duration parameter defines a rotation window: the time range within which rotation can start after the scheduled time. This is useful when you want rotation to happen during a low-traffic period but do not need it at an exact minute.

# Rotate every 30 days, within a 4-hour window starting at the scheduled time
aws secretsmanager rotate-secret \
  --secret-id "prod/myapp/database" \
  --rotation-rules '{"ScheduleExpression":"rate(30 days)","Duration":"4h"}'

How applications should handle rotated secrets

Configuring rotation is only half the work. Your application must be designed to handle credential changes gracefully.

Cache with a TTL

Do not fetch the secret on every request (expensive and slow), but do not cache it forever either. A TTL of 5 to 15 minutes is a common starting point. The AWS Secrets Manager caching libraries (available for Java, Python, .NET, Go, and JavaScript) handle this automatically.

Retry on authentication failure

When a database connection fails with an authentication error, fetch a fresh secret and retry before giving up. This handles the brief window where the cached password is the old one and the database now expects the new one.

import boto3
import json
import psycopg2
import time

_cache = {'value': None, 'fetched_at': 0}
CACHE_TTL = 300  # 5 minutes

def get_secret(force_refresh=False):
    now = time.time()
    if not force_refresh and _cache['value'] and (now - _cache['fetched_at']) < CACHE_TTL:
        return _cache['value']
    client = boto3.client('secretsmanager')
    result = client.get_secret_value(SecretId='prod/myapp/postgres')
    _cache['value'] = json.loads(result['SecretString'])
    _cache['fetched_at'] = now
    return _cache['value']

def get_db_connection():
    secret = get_secret()
    for attempt in range(3):
        try:
            return psycopg2.connect(
                host=secret['host'], database=secret['dbname'],
                user=secret['username'], password=secret['password'],
                port=secret['port']
            )
        except psycopg2.OperationalError as e:
            if "password authentication failed" in str(e) and attempt < 2:
                time.sleep(1)
                secret = get_secret(force_refresh=True)
            else:
                raise

Refresh connection pools

If your application uses a connection pool, existing connections hold the old password. New connections will use whatever the pool’s credential source provides. Design your pool to:

• Periodically cycle out old connections (most connection pool libraries have a max-lifetime setting).
• Handle authentication errors by evicting the failed connection and fetching a fresh secret for the replacement.