AWS Secrets Manager
User Guide

Understanding and Customizing Your Lambda Rotation Function

For details about how a Lambda rotation function works, see Overview of the Lambda Rotation Function.

If you choose one of the supported databases for your secret type, AWS Secrets Manager creates and configures the Lambda rotation function for you. You can enable rotation for those databases by following the steps in Enabling Rotation for an RDS Database Secret. However, if you want to create a custom Lambda rotation function for another service, then you must follow the steps in Enabling Rotation for a Secret for Another Database or Service.

This section describes in detail how the Lambda function operates and how it must be configured to successfully rotate your secrets.


The Lambda function and the Secrets Manager secret that invokes it must be in the same AWS region. If they are in different regions, then you get a "Lambda does not exist" error message when you try to add the ARN of the function to the secret's metadata.

The following are the primary scenarios to consider when creating your own Lambda function for rotation. Which scenario applies is determined by the features supported by the authentication system that protects the secured resource and by your security concerns.

  • You can change only the password for a single user. This is a common scenario for services that are owned by someone other than the user accessing the service. The owner of the service lets the customer create one user account, often with something like the user's email address as the user name itself, or at least as a uniqueness key. In this scenario, the service typically allows the user to change the password as often as is required, but does not allow the user to create additional users, and often does not even allow the user name to change.

    Users typically have the ability to change their own password and do not require a separate user with admin permissions to do the password change. However, because you are changing the password on the single, live user, clients that access the service with this user might temporarily fail to sign in while the password change is in progress. The potential for downtime exists between when the password is changed and when the clients all get notified to use the newer version of the password. This should typically be only on the order of a few seconds and must be allowed for in your application code that uses the secret. Be sure to enable retries with some delay in between to be tolerant of this short term outage during a rotation.

  • You can create two users that you can alternate between. In this scenario, you can create one user that the rotation process clones to make two users that have equal access to the secured resource. The rotation process alternates between the two users, changing the password and testing the "inactive" one while your users continue to access the database or service using the credentials in the "active" secret.

    While your clients are all accessing the secured resource with one user name by querying for the version that has the default staging label AWSCURRENT attached, the rotation function changes the password on the currently inactive second user and stores that updated password in a new version of the secret that has the staging label AWSCURRENT. After testing, you move the staging label AWSCURRENT to the new version that points to the alternate user and its new password. All of the clients immediately begin accessing the secured resource with the alternate user and its updated password. When it is time for the next rotation, you change the password on the original user account that is now idle, creating another new version of the secret and repeating the cycle.

    This scenario requires a second secret that points to an admin or super user that has permissions to change the password on both users.

  • You can create new credentials for a single user. Some systems enable you to create a single user, but access that user with multiple sets of credentials. For example, , AWS Identity and Access Management enables you to create a user with two access keys. Each access key is a complete set of credentials and operates independently of the other. You can delete and recreate the first access key while the second is in use, and then switch all of your clients to use the new first key. The next time you rotate, you delete and recreate the second access key while customers to continue to use the second.

For additional details, and instructions on how to configure each scenario, see the following topics: