Secrets Manager Automatic Rotation

AWS Secrets Manager is a service that securely stores, retrieves, and manages secrets such as database passwords, API keys, and OAuth tokens. Automatic rotation is a built-in feature that periodically changes the secret value according to a schedule you define. This reduces the risk of credential compromise by ensuring secrets are regularly refreshed.

Static secrets are a major security vulnerability. If a password is leaked, the window of exposure is indefinite until someone manually changes it. Automatic rotation limits that window to the rotation interval (e.g., 30 days). It also helps meet compliance requirements like PCI DSS, HIPAA, and SOC 2, which mandate periodic credential rotation.

Secrets Manager uses an AWS Lambda function to perform the rotation. The function is provided by AWS for supported services (e.g., Amazon RDS, Amazon Redshift, Amazon DocumentDB) or you can write a custom Lambda function for other secrets. The rotation process follows a specific sequence of steps called "staging labels" to ensure zero downtime and consistency.

#### Staging Labels

Each version of a secret has one or more staging labels. The key labels are:

During rotation, the Lambda function creates a new version with the AWSPENDING label, then updates the target service (e.g., sets the new password on the RDS user), and finally marks the AWSPENDING version as AWSCURRENT while moving the old AWSCURRENT to AWSPREVIOUS.

Each version of a secret has a unique Version ID (a UUID). When you retrieve a secret, you can specify a Version ID or use the staging label. This immutability ensures that if you have a reference to a specific version, the secret value does not change out from under you.

You can enable rotation when creating a secret or later via the console, CLI, or SDK. For an existing secret, you must attach a Lambda function and set the rotation schedule.

CLI Example:

aws secretsmanager rotate-secret \
    --secret-id MyDatabaseSecret \
    --rotation-lambda-arn arn:aws:lambda:us-east-1:123456789012:function:MyRotationLambda \
    --rotation-rules '{"AutomaticallyAfterDays": 30}'

AWS provides pre-built Lambda rotation templates for:

For other services (e.g., custom database, API key), you must create a custom Lambda function.

If you write your own Lambda function, it must implement the following steps (as per the AWS rotation function blueprint):

Secrets Manager invokes the Lambda function with a JSON event that includes the step name and the ARN of the secret being rotated.

Secrets Manager supports replicating secrets to multiple regions. Rotation must be configured independently in each region. If you replicate a secret, the rotation schedule does not automatically synchronize across regions.

Every rotation event is logged in AWS CloudTrail, including the creation of new versions and the update of staging labels. You can monitor rotations using CloudTrail or Amazon EventBridge.

You can check the rotation status in the Secrets Manager console under the secret details page. The console shows the last rotation date, next rotation date, and rotation history. Use CloudWatch metrics and logs for Lambda function errors.

Secrets Manager charges $0.40 per secret per month and $0.05 per 10,000 API calls. Rotation itself does not incur additional charges beyond the secret storage and API calls made during rotation.

A SaaS company hosts customer databases on Amazon RDS for PostgreSQL. Each customer has a dedicated database with a unique username and password. The company uses Secrets Manager to store these credentials and enables automatic rotation every 30 days. The rotation Lambda function is deployed in the same VPC as the RDS instances, with a security group that allows inbound/outbound traffic on port 5432. The function uses the RDS IAM authentication to manage users. In production, with over 500 secrets, rotation is staggered to avoid simultaneous load on the database. The company monitors rotation via CloudWatch logs and alerts on failures. A common issue is that the Lambda function times out if the database is under heavy load; increasing the Lambda timeout to 5 minutes resolves this. Another challenge is that some legacy applications cache the secret and break after rotation; the company mitigates this by using short TTLs and implementing a secret refresh mechanism.

A financial services firm integrates with a third-party payment gateway using an API key. The key is stored in Secrets Manager and must be rotated every 90 days per compliance. Since the third-party does not support automatic key rotation via API, the firm uses a custom Lambda function that: (1) generates a new key, (2) calls the third-party's support API to register the new key, (3) updates the secret, and (4) deactivates the old key after a grace period. The Lambda function is triggered by a CloudWatch Events rule that invokes rotation. The firm also uses a second secret as a backup key to avoid downtime during rotation. A misconfiguration where the Lambda function lacked VPC endpoints caused the function to fail when trying to reach the third-party API over the internet; the fix was to place the Lambda in a public subnet with a NAT gateway.