Menu
AWS Secrets Manager
User Guide

Rotating Secrets for Supported Amazon RDS Databases

You can configure AWS Secrets Manager to automatically rotate the secret for an Amazon RDS database. Secrets Manager uses a Lambda function that Secrets Manager provides.

Supported RDS databases

For the purposes of the RDS options in Secrets Manager, a "supported" database means that when you enable rotation, Secrets Manager provides a complete, ready-to-run Lambda rotation function that is designed for that database. For any other type of RDS database, you can still rotate your secret. However, you must use the workflow for Other database. For those instructions, see Rotating AWS Secrets Manager Secrets for Other Databases or Services. The following list shows the RDS databases for which Secrets Manager provides and configures a complete, ready-to-use rotation function for you without any additional steps.

  • Amazon Aurora on Amazon RDS

  • MySQL running on Amazon RDS

  • PostgreSQL running on Amazon RDS

When you enable rotation for a secret with Credentials for RDS database as the secret type, Secrets Manager automatically creates and configures a Lambda rotation function for you and then equips your secret with the ARN of the function. Secrets Manager creates the IAM role associated with the function and configures it with all of the required permissions. If your RDS database is running in an Amazon Virtual Private Cloud (VPC), Secrets Manager also configures the Lambda function to communicate with that VPC. You typically don't need to do anything for this to work other than to provide a few details which determine how the Lambda function operates:

  • Specify the secret that has credentials with permissions to rotate the secret – Sometimes the user can change their own password. Other times, the user has very restricted permissions and cannot change their own password. Instead, you use a different admin or "super" user to change the user's credentials.

    You must specify which secret the rotation function can use to rotate the credentials on the secured database:

    • Use this secret: Choose this option if the credentials in the current secret have permissions in the database to change its own password. Choosing this option causes Secrets Manager to implement a Lambda function with a rotation strategy that changes the password for a single user with each rotation. For more information about this rotation strategy, see Rotating AWS Secrets Manager Secrets for One User with a Single Password Only.

      Considerations

      This is the "lower availability" option, because sign-in failures can occur between the moment when the old password is removed by the rotation and the moment when the updated password is made accessible as the new version of the secret. Such a time window is typically very short, on the order of a second or less. If you choose this option, ensure that your client apps implement an appropriate "backoff and retry with jitter" strategy in their code. The apps should generate an error only if sign-in fails several times over a longer period of time.

    • Use a secret that I have previously stored in AWS Secrets Manager: Choose this option if the credentials in the current secret have more restrictive permissions and cannot be used to update the credentials on the secured service, or you require high availability for the secret. To choose this option, create a separate "master" secret with credentials that have permission to create and update credentials on the secured service. Then choose that master secret from the list. Choosing this option causes Secrets Manager to implement a Lambda function with a rotation strategy that clones the initial user found in the secret and then alternates between the two users with each rotation, updating the password for the user that is becoming active. For more information about this rotation strategy, see Rotating AWS Secrets Manager Secrets By Switching Between Two Existing Users

      Considerations

      This is the "high availability" option because the old version of the secret continues to operate and service requests while the new version is prepared and tested. The old version is not deprecated until after the clients switch to the new version. There is no down time while changing between versions.

      This option requires the Lambda function to clone the permissions of original user and apply them to the a created second user. The function then alternates between the two users with each rotation.

      If you ever need to change the permissions granted to the users, ensure that you change permissions for both users.

  • You can customize the function – you can tailor the Secrets Manager-provided Lambda rotation function to meet your organization's requirements. For example, you could extend the testSecret phase of the function to test the new version with application-specific checks to ensure that the new secret works as expected. For instructions, see Customizing the Secrets Manager Provided Lambda Rotation Function