Manage and Rotate Secrets with AWS Secrets Manager

Intermediate12 min

Store, retrieve, and configure automatic rotation of secrets using AWS Secrets Manager for database credentials, API keys, and other sensitive data.

Prerequisites

-AWS CLI v2 installed and configured
-IAM permissions for Secrets Manager operations

Steps

Create a new secret

Store a new secret value in Secrets Manager with a descriptive name and optional tags for organization.

$ aws secretsmanager create-secret --name prod/my-app/db-credentials --description "Production database credentials" --secret-string '{"username":"admin","password":"S3cureP@ss!","host":"mydb.cluster-example.us-east-1.rds.amazonaws.com","port":5432}' --tags Key=Environment,Value=production Key=Application,Value=my-app

Avoid putting secrets directly in shell history. Use --secret-string file://secret.json to read from a file instead.

Retrieve a secret value

Fetch the current secret value and parse specific fields from the JSON payload.

$ aws secretsmanager get-secret-value --secret-id prod/my-app/db-credentials --query SecretString --output text | jq -r '.password'

Use --version-stage AWSPREVIOUS to retrieve the previous version of the secret, useful for verifying rotation worked correctly.

Enable automatic rotation

Configure a Lambda rotation function to automatically rotate the secret on a schedule.

$ aws secretsmanager rotate-secret --secret-id prod/my-app/db-credentials --rotation-lambda-arn arn:aws:lambda:us-east-1:111111111111:function:SecretsManagerRDSRotation --rotation-rules AutomaticallyAfterDays=30

AWS provides pre-built rotation Lambda functions for RDS, Redshift, and DocumentDB. Use the Serverless Application Repository to deploy them.

Trigger an immediate rotation

Manually trigger a rotation cycle to test the rotation function or rotate a potentially compromised credential immediately.

$ aws secretsmanager rotate-secret --secret-id prod/my-app/db-credentials

Rotation temporarily creates a new version staged as AWSPENDING. Ensure your application can handle brief credential transitions during the rotation window.

List secret versions and stages

Inspect the version history and staging labels to understand the current state of the secret and verify rotation completed successfully.

$ aws secretsmanager list-secret-version-ids --secret-id prod/my-app/db-credentials --query 'Versions[*].{VersionId:VersionId,Stages:VersionStages,Created:CreatedDate}' --output table

Full Script

full-script.sh

#!/bin/bash
# Secrets Manager Operations
# Usage: ./manage-secret.sh <action> <secret-name> [secret-file]
# Actions: create, get, rotate, list

set -euo pipefail

ACTION="${1:?Usage: $0 <create|get|rotate|list> <secret-name> [secret-file]}"
SECRET_NAME="${2:?Provide secret name}"

case "$ACTION" in
  create)
    SECRET_FILE="${3:?Provide path to secret JSON file}"
    if [ ! -f "$SECRET_FILE" ]; then
      echo "Secret file not found: $SECRET_FILE"
      exit 1
    fi
    aws secretsmanager create-secret \
      --name "$SECRET_NAME" \
      --description "Managed secret for $SECRET_NAME" \
      --secret-string "file://$SECRET_FILE"
    echo "Secret created: $SECRET_NAME"
    rm -f "$SECRET_FILE"
    echo "Secret file deleted for security."
    ;;

  get)
    echo "=== Secret: $SECRET_NAME ==="
    aws secretsmanager get-secret-value \
      --secret-id "$SECRET_NAME" \
      --query SecretString --output text | jq .
    ;;

  rotate)
    echo "Triggering rotation for $SECRET_NAME ..."
    aws secretsmanager rotate-secret --secret-id "$SECRET_NAME"
    echo "Rotation initiated. Check versions:"
    aws secretsmanager list-secret-version-ids \
      --secret-id "$SECRET_NAME" \
      --query 'Versions[*].{VersionId:VersionId,Stages:VersionStages}' \
      --output table
    ;;

  list)
    echo "=== Versions for $SECRET_NAME ==="
    aws secretsmanager list-secret-version-ids \
      --secret-id "$SECRET_NAME" \
      --query 'Versions[*].{VersionId:VersionId,Stages:VersionStages,Created:CreatedDate}' \
      --output table
    ;;

  *)
    echo "Unknown action: $ACTION"
    echo "Valid actions: create, get, rotate, list"
    exit 1
    ;;
esac

FAQ

Discussion

Loading comments...

#!/bin/bash # Secrets Manager Operations # Usage: ./manage-secret.sh <action> <secret-name> [secret-file] # Actions: create, get, rotate, list set -euo pipefail ACTION="${1:?Usage: $0 <create|get|rotate|list> <secret-name> [secret-file]}" SECRET_NAME="${2:?Provide secret name}" case "$ACTION" in create) SECRET_FILE="${3:?Provide path to secret JSON file}" if [ ! -f "$SECRET_FILE" ]; then echo "Secret file not found: $SECRET_FILE" exit 1 fi aws secretsmanager create-secret \ --name "$SECRET_NAME" \ --description "Managed secret for $SECRET_NAME" \ --secret-string "file://$SECRET_FILE" echo "Secret created: $SECRET_NAME" rm -f "$SECRET_FILE" echo "Secret file deleted for security." ;; get) echo "=== Secret: $SECRET_NAME ===" aws secretsmanager get-secret-value \ --secret-id "$SECRET_NAME" \ --query SecretString --output text | jq . ;; rotate) echo "Triggering rotation for $SECRET_NAME ..." aws secretsmanager rotate-secret --secret-id "$SECRET_NAME" echo "Rotation initiated. Check versions:" aws secretsmanager list-secret-version-ids \ --secret-id "$SECRET_NAME" \ --query 'Versions[*].{VersionId:VersionId,Stages:VersionStages}' \ --output table ;; list) echo "=== Versions for $SECRET_NAME ===" aws secretsmanager list-secret-version-ids \ --secret-id "$SECRET_NAME" \ --query 'Versions[*].{VersionId:VersionId,Stages:VersionStages,Created:CreatedDate}' \ --output table ;; *) echo "Unknown action: $ACTION" echo "Valid actions: create, get, rotate, list" exit 1 ;; esac