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 Amazon RDS Databases

For the purposes of the Amazon 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's designed for that database. For a complete list of the supported databases, see Databases with Fully Configured and Ready-to-Use Rotation Support. For any other type of 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.

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. Then it equips your secret with the Amazon Resource Name (ARN) of the function. Secrets Manager creates the IAM role that's associated with the function and configures it with all of the required permissions.

If your Amazon RDS DB instance is running in a VPC provided by Amazon VPC and that VPC doesn't have public internet access, then Secrets Manager also configures the Lambda function to run within that VPC. The other requirement is that the Lambda rotation function must be able to access a Secrets Manager service endpoint to call the required API operations. If one or more of your resources in the VPC must communicate with the internet, then you can configure the VPC with a NAT gateway to enable the Lambda rotation function to query the public Secrets Manager service endpoint. If there is no other need to communicate with the internet, you can configure the VPC with a private Secrets Manager service endpoint that's accessible from within the VPC.

Otherwise, you typically only need to provide a few details that determine which template is used to construct the Lambda function:

  • 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 can't change their own password. Instead, you must use the credentials for a different administrator 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.

      Considerations

      This option is the "lower availability" option. This is 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. This time window is typically very short—on the order of a second or less. If you choose this option, make sure 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 can't be used to update the credentials on the secured service. Or choose this if 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. This Lambda function has a rotation strategy that clones the initial user that's found in the secret. Then it alternates between the two users with each rotation, and updates the password for the user that's becoming active. For more information about this rotation strategy, see Rotating AWS Secrets Manager Secrets by Alternating Between Two Existing Users.

      Considerations

      This is the "high availability" option because the old version of the secret continues to operate and handle service requests while the new version is prepared and tested. The old version isn't deprecated until after the clients switch to the new version. There's no downtime while changing between versions.

      This option requires the Lambda function to clone the permissions of the original user and apply them to the new 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 Lambda rotation function that's provided by Secrets Manager 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 Lambda Rotation Function Provided by Secrets Manager.