AWS Secrets Manager
User Guide

Rotating Secrets for Amazon DocumentDB

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

Amazon DocumentDB is a supported service

Secrets Manager supports Amazon DocumentDB which means that when you enable rotation, Secrets Manager provides a complete, ready-to-run Lambda rotation function designed for Amazon DocumentDB.

When you enable rotation for a secret with Credentials for DocumentDB 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 that you want to use with your new secret, you can specify the ARN of the existing function and use it for both secrets.

If your Amazon DocumentDB 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 to determine which template you can use to construct the Lambda function:

  • Specify the secret with credentials and 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 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 the 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.


      This option is the "lower availability" option. This is because sign-in failures can occur between the moment when Secrets Manager removes the old password by the 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 with 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 found in the secret. Then it 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.


      This is the "high availability" option 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.