Automatically rotate an Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret - AWS Secrets Manager

Automatically rotate an Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret

Secrets Manager provides complete rotation templates for Amazon RDS, Amazon DocumentDB, and Amazon Redshift secrets. For other types of secrets, see Automatically rotate a secret.

Rotation functions for Amazon RDS (except Oracle) and Amazon DocumentDB automatically use Secure Socket Layer (SSL) or Transport Layer Security (TLS) to connect to your database, if it is available. Otherwise they use an unencrypted connection.

Note

If you set up automatic secret rotation before December 20, 2021, your rotation function might be based on an older template that did not support SSL/TLS. See Determine when your rotation function was created. If it was created before December 20, 2021, to support connections that use SSL/TLS, you need to recreate your rotation function.

Edit your secret, and then choose Edit rotation. In the dialog box, choose Create a rotation function to recreate your rotation function. If you made customizations to your previous rotation function, you must redo them in the new rotation function.

Another way to automatically rotate a secret is to use AWS CloudFormation to create the secret, and include AWS::SecretsManager::RotationSchedule. See Create secrets in AWS CloudFormation.

Before you begin, you need the following:

  • A user with credentials to Amazon RDS, Amazon DocumentDB, or Amazon Redshift.

  • A rotation strategy. See Rotation strategies.

  • If you use the Alternating users rotation strategy, you need a separate secret that contains credentials that can update the rotating secret's credentials.

To turn on rotation for an Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret (console)

  1. Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/.

  2. On the Secrets page, choose your secret.

  3. On the Secret details page, in the Rotation configuration section, choose Edit rotation.

  4. In the Edit rotation configuration dialog box, do the following:

    1. Turn on Automatic rotation.

    2. Under Rotation schedule, enter your schedule in UTC time zone by doing one of the following:

      • Choose Schedule expression builder to build a schedule in a form. Secrets Manager stores your schedule as a rate() or cron() expression. The rotation window automatically starts at midnight unless you specify a Start time.

      • Choose Schedule expression, and then do one of the following:

        • Enter the cron expression for your schedule, for example, cron(0 21 L * ? *), which rotates the secret on the last day of every month at 9:00 PM UTC+0. A cron expression for Secrets Manager must have 0 in the minutes field because Secrets Manager rotation windows open on the hour. It must have * in the year field, because Secrets Manager does not support rotation schedules that are more than a year apart. For more information, see Schedule expressions.

        • Enter a rate expression for a daily rate, for example, rate(10 days), which rotates the secret every 10 days. The expression must include rate(). With a rate expression, the rotation window automatically starts at midnight.

    3. (Optional) For Window duration, choose the length of the window during which you want Secrets Manager to rotate your secret, for example 3h for a three hour window. The window must not go into the next UTC day. The rotation window automatically ends at the end of the day if you don't specify Window duration.

    4. (Optional) Choose Rotate immediately when the secret is stored to rotate your secret when you save your changes. If you clear the checkbox, then the first rotation will begin on the schedule you set.

      If you use Alternating users rotation strategy, the credentials in the previous version of the secret are still valid and can be used to access the database or service. To meet compliance requirements, you might need to rotate your secrets more often. For example, if your credential lifetime maximum is 90 days, then we recommend you set your rotation interval to 44 days. That way both users' credentials will be updated within 90 days.

    5. Under Rotation function, do the following:

      • To have Secrets Manager create a rotation function for you based on the Rotation function templates for your secret, choose Create a new Lambda function and enter a name for your new function. Secrets Manager adds "SecretsManager" to the beginning of your function name.

      • To use a rotation function that you or Secrets Manager already created, choose Use an existing Lambda function. You can reuse a rotation function you used for another secret if the rotation strategy is the same. The rotation functions listed under Recommended VPC configurations have the same VPC and security group as the database, so you don't have to make any changes for the rotation function to be able to make calls to the database.

    6. For Use separate credentials to rotate this secret, do one of the following:

For help resolving common rotation issues, see Troubleshoot AWS Secrets Manager rotation of secrets.

AWS CLI

To turn on rotation, see rotate-secret.

For Secrets Manager to be able to rotate the secret, you must make sure the JSON matches the JSON structure of a database secret. In particular, if you want to use the Alternating users strategy, your secret must contain the ARN of a superuser secret.

You also need a Lambda function that can rotate the secret. You can create this function based on the Secrets Manager rotation function templates that Secrets Manager provides. For Single user, choose a template for single user rotation. For Alternating users, choose a template for alternating users rotation.

To turn on automatic rotation

  • In the AWS CLI, the following command turns on automatic rotation. Secrets Manager rotates the secret once immediately, and then on the 1st and 15th day of every month between 4:00 PM and 6:00 PM UTC.

    aws secretsmanager rotate-secret --secret-id MySecret --rotation-lambda-arn arn:aws:lambda:us-east-2:123456789012:function:SecretsManagerMyLambdaFunction-alt-users --rotation-rules "{\"ScheduleExpression\": \"cron(0 16 1,15 * ? *)\", \"Duration\": \"2h\"}"

AWS SDK

To turn on rotation, use the RotateSecret action. For more information, see AWS SDKs.