Rotation by Lambda function - AWS Secrets Manager

Rotation by Lambda function

For many types of secrets, Secrets Manager uses an AWS Lambda function to update the secret and the database or service. For information about the costs of using a Lambda function, see Pricing.

For some Secrets managed by other services, you use managed rotation. To use Managed rotation, you first create the secret through the managing service.

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

To rotate a secret, Secrets Manager calls a Lambda function according to the rotation schedule you set up. If you also manually update your secret value while automatic rotation is set up, then Secrets Manager considers that a valid rotation when it calculates the next rotation date.

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",
    "RotationToken" : "string"
}
Parameters:

  • Step – The rotation step: create_secret, set_secret, test_secret, or finish_secret. For more information, see Four steps in a rotation function.

  • SecretId – The ARN of the secret to rotate.

  • ClientRequestToken – A unique identifier for the new version of the secret. This value helps ensure idempotency. For more information, see PutSecretValue: ClientRequestToken in the AWS Secrets Manager API Reference.

  • RotationToken – A unique identifier that indicates the source of the request. Required for secret rotation using an assumed role or cross-account rotation, in which you rotate a secret in one account by using a Lambda rotation function in another account. In both cases, the rotation function assumes an IAM role to call Secrets Manager and then Secrets Manager uses the rotation token to validate the IAM role identity.

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

Topics