Lambda rotation functions - Amazon Secrets Manager
Four steps in a rotation function
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Lambda rotation functions

In Rotation by Lambda function, a Lambda function does the work of rotating the secret. Secrets Manager uses staging labels to label secret versions during rotation.

If Secrets Manager doesn't provide a rotation function template for your type of secret, you can create a rotation function. When writing a rotation function, follow the guidance for each step.

Tips for writing your own rotation function

  • Use the generic rotation template as a starting point to write your own rotation function.

  • As you write your function, be cautious about including debugging or logging statements. These statements can cause information in your function to be written to Amazon CloudWatch, so you need to make sure the log doesn't include any sensitive information collected during development.

    For examples of log statements, see the Amazon Secrets Manager rotation function templates source code.

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

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

  • If you use external binaries and libraries, for example to connect to a resource, you must manage patching them and keeping them up-to-date.

  • Save your rotation function in a ZIP file my-function.zip along with any required dependencies.

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 Amazon 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 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.