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 when you enable rotation, Secrets Manager provides a complete, ready-to-run Lambda rotation function 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 can automatically create and configure a Lambda rotation function for you. Then Secrets Manager equips your secret with the Amazon Resource Name (ARN) of the function. Secrets Manager creates the IAM role associated with the function and configures it with all of the required permissions. Alternatively, if you already have another secret that uses the same rotation strategy you want to use with your new secret, you can specify the ARN of the existing function and use it for both secrets.

If you run your Amazon RDS DB instance in a VPC provided by Amazon VPC and the VPC doesn't have public Internet access, then Secrets Manager also configures the Lambda function to run within the 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 accessible from within the VPC.

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

  • Specify the secret with credentials and permissions to rotate the secret: Sometimes the user can change their password. Other times, the user has very restricted permissions and can't change their password. Instead, you must use the credentials for a different administrator or "super" user to change the user 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 provides "lower availability". Because sign-in failures can occur between the moment when Secrets Manager removes the old password by rotation and the moment when the updated password becomes 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 applications 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 and permissions 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 found in the secret. Then Secrets Manager alternates between the two users with each rotation, and updates the password for the user becoming active. For more information about this rotation strategy, see Rotating AWS Secrets Manager Secrets by Alternating Between Two Existing Users.

      Considerations

      This provides "high availability" because the old version of the secret continues to operate and handle service requests while Secrets Manager prepares and tests the new version. Secrets Manager doesn't deprecate the old version 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 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.