Set up automatic rotation for AWS Secrets Manager secrets

This tutorial describes how to set up Rotation by Lambda function. 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 that the secret is for.

To set up rotation using the console, you first configure the secret for rotation. During that step, you also create an empty Lambda rotation function. Next, you set permissions for the rotation function and for the Lambda execution role. Then you write the rotation function code. The last step is to make sure that the Lambda rotation function can access both Secrets Manager and your database or service through the network.

For database secrets, see Set up automatic rotation for Amazon RDS, Amazon Aurora, Amazon Redshift, or Amazon DocumentDB secrets.

To turn on automatic rotation, you must have permission to create the IAM execution role and attach a permission policy to it. You need both iam:CreateRole and iam:AttachRolePolicy permissions.

Warning

Granting an identity both iam:CreateRole and iam:AttachRolePolicy permissions allows the identity to grant themselves any permissions.

Step 1: Configure the secret for rotation

In this step, you set a rotation schedule for your secret and create an empty rotation function. Your secret will not be rotated until you finish writing the rotation function. If you schedule rotation before the rotation function is written, or if it fails for any reason, Secrets Manager will retry the rotation function multiple times.

To configure rotation and create an empty rotation function

1. Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/.

2. On the Secrets page, choose your secret.

3. On the Secret details page, in the Rotation configuration section, choose Edit rotation. In the Edit rotation configuration dialog box, do the following:

   1. Turn on Automatic rotation.

   2. Under Rotation schedule, enter your schedule in UTC time zone in either the Schedule expression builder or as a Schedule expression. Secrets Manager stores your schedule as a rate() or cron() expression. The rotation window automatically starts at midnight unless you specify a Start time. You can rotate a secret as often as every four hours. For more information, see Rotation schedules.

   3. (Optional) For Window duration, choose the length of the window during which you want Secrets Manager to rotate your secret, for example 3h for a three hour window. The window must not extend into the next rotation window. If you don't specify Window duration, for a rotation schedule in hours, the window automatically closes after one hour. For a rotation schedule in days, the window automatically closes at the end of the day.

   4. (Optional) Choose Rotate immediately when the secret is stored to rotate your secret when you save your changes. If you clear the checkbox, then the first rotation will begin on the schedule you set.

   5. Under Rotation function, choose Create function. The Lambda console opens in a new window.

      1. In the Lambda console, on the Create function page, do one of the following:

         • If you see Browse serverless app repository, choose it.

           1. Under Public applications, in the search box, enter SecretsManagerRotationTemplate.

           2. Choose Show apps that create custom IAM roles or resource policies.

           3. Choose the SecretsManagerRotationTemplate tile.

           4. On the Review, configure and deploy page, in the Application settings tile, fill in the required fields, and then choose Deploy. For a list of endpoints, see AWS Secrets Manager endpoints.

         • If you don't see Browse serverless app repository, your AWS Region might not support the AWS Serverless Application Repository. Choose Author from scratch.

           1. For Function name, enter a name for your rotation function.

           2. For Runtime, choose Python 3.9.

           3. When the new Lambda function opens, scroll down to choose Configuration, and then on the left choose Permissions.

           4. Scroll down to Resource-based policy and choose Add permissions to grant permission for Secrets Manager to invoke the function. To attach a resource policy to a Lambda function, see Using resource-based policies for Lambda.

              The following policy shows how to allow Secrets Manager to invoke the Lambda function.

              {
                  "Version": "2012-10-17",
                  "Id": "default",
                  "Statement": [
                  {
                      "Effect": "Allow",
                      "Principal": {
                          "Service": "secretsmanager.amazonaws.com"
                          },
                      "Action": "lambda:InvokeFunction",
                      "Resource": "LambdaRotationFunctionARN"
                  }
                  ]
              }

   6. Switch back to the Secrets Manager console to attach the new rotation function to your secret.

   7. For Lambda rotation function, choose the refresh button. Then in the list of functions, choose your new function.

   8. Choose Save.

Step 2: Set permissions for the rotation function

The Lambda rotation function needs permission to access the secret in Secrets Manager, and it needs permission to access your database or service. In this step, you grant these permissions to the Lambda execution role. If the secret is encrypted with a KMS key other than the AWS managed key aws/secretsmanager, then you need to grant the Lambda execution role permission to use the key. You can use the SecretARN encryption context to limit the use of the decrypt function, so the rotation function role only has access to decrypt the secret it is responsible for rotating. For policy examples, see Permissions for rotation.

For instructions, see Lambda execution role in the AWS Lambda Developer Guide.

Step 3: (Optional) Set an additional permissions condition on the rotation function

In the resource policy for your rotation function, we recommend that you include the context key aws:SourceAccount to help prevent Lambda from being used as a confused deputy. For some AWS services, to avoid the confused deputy scenario, AWS recommends that you use both the aws:SourceArn and aws:SourceAccount global condition keys. However, if you include the aws:SourceArn condition in your rotation function policy, the rotation function can only be used to rotate the secret specified by that ARN. We recommend that you include only the context key aws:SourceAccount so that you can use the rotation function for multiple secrets.

To update your rotation function resource policy

1. In the Secrets Manager console, choose your secret, and then on the details page, under Rotation configuration, choose the Lambda rotation function. The Lambda console opens.

2. Follow the instructions at Using resource-based policies for Lambda to add a aws:sourceAccount condition.

   "Condition": {
       "StringEquals": {
           "AWS:SourceAccount": "123456789012"
       }
   },

Step 4: Set up network access for the rotation function

See Network access for Lambda rotation function.

Step 5: Write the rotation function code

The rotation function you created in Step 1 is a starting point for your function. You write the code for your specific use case. For more information, see Lambda rotation functions.

Next steps

See Troubleshoot AWS Secrets Manager rotation.