Lambda rotation functions

In Rotation by Lambda function, an AWS Lambda function rotates the secret. AWS Secrets Manager uses staging labels to identify secret versions during rotation.

If AWS Secrets Manager doesn't provide a rotation function template for your secret type, you can create a custom rotation function. Follow these guidelines when writing your rotation function:

Best practices for custom rotation functions

• Use the generic rotation template as a starting point.

• Be cautious with debugging or logging statements. They can write information to Amazon CloudWatch Logs. Ensure logs don't contain sensitive information.

  For log statement examples, see the AWS Secrets Manager rotation function templates source code.

• For security, AWS Secrets Manager only allows a Lambda rotation function to rotate the secret directly. The rotation function can't call another Lambda function to rotate the secret.

• For debugging guidance, see Testing and debugging serverless applications.

• If you use external binaries and libraries, for example to connect to a resource, you're responsible for patching and updating them.

• Package your rotation function and any dependencies in a ZIP file, such as my-function.zip.

Four steps in a rotation function

create_secret: Create a new version of the secret

The method create_secret first checks if a secret exists by calling get_secret_value with the passed-in ClientRequestToken. If there's no secret, it creates a new secret with create_secret and the token as the VersionId. Then it generates a new secret value with get_random_password. Next it calls put_secret_value to store it with the staging label AWSPENDING. Storing the new secret value in AWSPENDING helps ensure idempotency. If rotation fails for any reason, you can refer to that secret value in subsequent calls. See How do I make my Lambda function idempotent.

Tips for writing your own rotation function

• Ensure the new secret value only includes characters that are valid for the database or service. Exclude characters by using the ExcludeCharacters parameter.

• As you test your function, use the AWS CLI to see version stages: call describe-secret and look at VersionIdsToStages.

• For Amazon RDS MySQL, in alternating users rotation, Secrets Manager creates a cloned user with a name no longer than 16 characters. You can modify the rotation function to allow longer usernames. MySQL version 5.7 and higher supports usernames up to 32 characters, however Secrets Manager appends "_clone" (six characters) to the end of the username, so you must keep the username to a maximum of 26 characters.

set_secret: Change the credentials in the database or service

The method set_secret changes the credential in the database or service to match the new secret value in the AWSPENDING version of the secret.

Tips for writing your own rotation function

• If you pass statements to a service that interprets statements, like a database, use query parameterization. For more information, see Query Parameterization Cheat Sheet on the OWASP web site.

• The rotation function is a privileged deputy that has the authorization to access and modify customer credentials in both the Secrets Manager secret and the target resource. To prevent a potential confused deputy attack, you need to make sure that an attacker cannot use the function to access other resources. Before you update the credential:

  • Check that the credential in the AWSCURRENT version of the secret is valid. If the AWSCURRENT credential isn't valid, abandon the rotation attempt.

  • Check that the AWSCURRENT and AWSPENDING secret values are for the same resource. For a username and password, check that the AWSCURRENT and AWSPENDING usernames are the same.

  • Check that the destination service resource is the same. For a database, check that the AWSCURRENT and AWSPENDING host names are the same.

• In rare cases, you might want to customize an existing rotation function for a database. For example, with alternating users rotation, Secrets Manager creates the cloned user by copying the runtime configuration parameters of the first user. If you want to include more attributes, or change which ones are granted to the cloned user, you need to update the code in the set_secret function.

test_secret: Test the new secret version

Next, the Lambda rotation function 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.

finish_secret: Finish the rotation

Finally, the Lambda rotation function moves the label AWSCURRENT from the previous secret version to this version, which also removes the AWSPENDING label in the same API call. Secrets Manager adds the AWSPREVIOUS staging label to the previous version, so that you retain the last known good version of the secret.

The method finish_secret uses update_secret_version_stage to move the staging label AWSCURRENT from the previous secret version to the new secret version. Secrets Manager automatically adds the AWSPREVIOUS staging label to the previous version, so that you retain the last known good version of the secret.

Tips for writing your own rotation function

• Don't remove AWSPENDING before this point, and don't remove it by using a separate API call, because that can indicate to Secrets Manager that the rotation did not complete successfully. Secrets Manager adds the AWSPREVIOUS staging label to the previous version, so that you retain the last known good version of the secret.

When rotation is successful, the AWSPENDING staging label might be attached to the same version as the AWSCURRENT version, or it might not be attached to any version. If the AWSPENDING staging label is present but not attached to the same version as AWSCURRENT, then any later invocation of rotation assumes that a previous rotation request is still in progress and returns an error. When rotation is unsuccessful, the AWSPENDING staging label might be attached to an empty secret version. For more information, see Troubleshoot rotation.