Rotate AWS Secrets Manager secrets - AWS Secrets Manager
How rotation works

Rotate AWS Secrets Manager secrets

Rotation is the process of periodically updating a secret. When you rotate a secret, you update the credentials in both the secret and the database or service. In Secrets Manager, you can set up automatic rotation for your secrets.

Topics

How rotation works

To rotate a secret, Secrets Manager calls a Lambda function according to the schedule you set up. Secrets Manager uses staging labels to label secret versions during rotation. During rotation, Secrets Manager calls the same function several times, each time with different parameters. Secrets Manager invokes the function with the following JSON request structure of parameters: 

{
    "Step" : "request.type",
    "SecretId" : "string",
    "ClientRequestToken" : "string"
}

The rotation function does the work of rotating the secret. There are four steps to rotating a secret, which correspond to the following four steps in the Lambda rotation function:

  1. Create a new version of the secret (createSecret)

    The first step of rotation is to create a new version of the secret. The new version can contain a new password, a new username and password, or more secret information. Secrets Manager labels the new version with the staging label AWSPENDING.

  2. Change the credentials in the database or service (setSecret)

    Next, rotation changes the credentials in the database or service to match the new credentials in the AWSPENDING version of the secret. Depending on your rotation strategy, this step can create a new user with the same permissions as the existing user.

    Rotation functions for Amazon RDS (except Oracle) and Amazon DocumentDB automatically use Secure Socket Layer (SSL) or Transport Layer Security (TLS) to connect to your database, if it is available. Otherwise they use an unencrypted connection.

    Note

    If you set up automatic secret rotation before December 20, 2021, your rotation function might be based on an older template that did not support SSL/TLS. See Determine when your rotation function was created. If it was created before December 20, 2021, to support connections that use SSL/TLS, you need to recreate your rotation function.

  3. Test the new secret version (testSecret)

    Next, rotation tests the AWSPENDING version of the secret by using it to access the database or service. Rotation functions based on Rotation function templates test the new secret by using read access. Depending on the type of access your applications need, you can update the function to include other access such as write access.

  4. Finish the rotation (finishSecret)

    Finally, rotation moves the label AWSCURRENT from the previous secret version to this version. Secrets Manager adds the AWSPREVIOUS staging label to the previous version, so that you retain the last known good version of the secret.

During rotation, Secrets Manager logs events that indicate the state of rotation. For more information, see Logging AWS Secrets Manager events with AWS CloudTrail.

If any rotation step fails, Secrets Manager retries the entire rotation process multiple times.

After rotation is successful, applications that Retrieve secrets from AWS Secrets Manager from Secrets Manager automatically get the updated credentials. For more details about how each step of rotation works, see the AWS Secrets Manager rotation function templates.