AWS Secrets Manager now enables you to specify a Rotation window for each secret stored. With this launch, you can continue to follow best practice of regularly rotating your secrets, while using the defined time window of your choice.

With Secrets Manager, you can manage, retrieve, and rotate database credentials, API keys, and other secrets. With the rotation window feature, you can specify a rotation window, allowing you to rotate your secrets during non-critical business hours or scheduled maintenance windows. You can rotate your secrets using an AWS-provided Lambda rotation function, or create a custom Lambda rotation function.

Previously, you could only specify the rotation interval in days for automatic rotation. AWS Secrets Manager would then rotate the secret within the last 24 hours of the scheduled rotation interval. As per best practice, you might implement secret caching. However, rotating the secret when the application is at its peak usage places a higher burden on applications to refresh secret caches and manage retries when secrets were rotated. In contrast, the custom rotation window feature gives you better control and flexibility on when rotation occurs. This makes it easier and operationally simpler to rotate your secrets using Secrets Manager.

Secrets Manager supports familiar cron and rate expressions to specify rotation frequency with rotation windows. In this blog post, we will go through the two ways you can specify a custom rotation window to rotate your secret, and how you can set up a custom rotation window for existing secrets. This post describes the following processes:

1. Set up rotation window using the interactive schedule expression builder
2. Set up rotation window by directly specifying a cron expression
3. Enabling a custom rotation window for an existing secret

Prerequisites

The procedures described in this blog post require that you complete the following steps before starting:

1. Configure an Amazon RDS DB instance, including creating one or more users depending on your rotation strategy. To learn more about rotation strategies, see Rotation Strategies.
2. Sign in to the AWS Management Console using a role that has SecretsManagerReadWrite permission.
3. Configure the Lambda function to connect with the Amazon RDS database and Secrets Manager by following the procedure in this blog post.

Use case 1: Set up rotation window using Schedule expression builder

This blog post assumes that your organization follows best practice by rotating secrets that contain database credentials of an application, and you want to avoid application downtime by rotating these secrets during off-peak hours. Using the custom rotation feature, you can limit rotation to occur within a specified timeframe on any weekday.

Your application has lowest usage during the window from 3:00 AM to 5:00 AM UTC, and you must rotate secrets once a month as part of your rotation policy. To accommodate these requirements, you can specify a rotation window that occurs on the second Monday of every month, between 3:00 AM to 5:00 AM UTC.

For this example, we will be using the Schedule expression builder. This is an interactive feature that enables you to create your rotation window based on common rotation window patterns. It then converts it to a cron expression on your behalf.

To set up rotation window using Schedule expression builder

1. Log into the AWS Management Console, and navigate to the Secrets Manager console in the region where you launched your RDS instance.
2. Choose Store a new secret.
3. On the Store a new secret screen, enter the Amazon RDS database credentials that will be used to connect with the Amazon RDS DB instance. Select the encryption key and the Amazon RDS DB instance, and then choose Next.
4. Enter the secret name of your choice. You can optionally provide a Description of the secret, create tags, and add resource permissions to the secret. Optionally, you can also replicate the secret to another region to meet your organization’s disaster recovery requirements by following the procedure in this blog post.
5. Choose Next.
   

   Figure 1: Create a secret to store your RDS Database credentials

6. Turn on Automatic rotation to enable rotation for the secret.
7. Under Rotation schedule, choose Schedule expression builder.
   1. For the Time Unit choose Months, then enter a value of 1.
   2. For the Start day choose Second from the drop-down menu and Monday in the value field.
   3. In the Start time field enter a value of 3. This ensures rotation does not start until 3:00 AM UTC every second Monday of the month.
   4. In the Window duration field type 2h. This provides Secrets Manager with a two-hour period to rotate the secret. The rotation window ends at 5:00 AM UTC.
   5. For this example, keep the check box marked to rotate the secret immediately. For security reasons, it’s recommended that you immediately rotate any password you enter manually. In future, you can choose to skip immediate rotation if the time at which you are editing rotation settings does not align with your chosen rotation window. If you skip the first rotation, the service will still test rotation settings and permissions, but will actually rotate the secret in the next scheduled rotation window.
      

      Figure 2: Enable automatic rotation using the Schedule expression builder

8. Under Rotation function, choose your Lambda rotation function from the dropdown menu.
9. Choose Next.
10. On the Secret review page, you are provided with an overview of the secret. Review the secret and scroll down to the Rotation schedule section.
11. Confirm the custom Rotation schedule and Next rotation date meets your requirements. The values entered into the Schedule expression builder is then converted into a cron expression.
    

    Figure 3: Rotation schedule with a summary of the configured custom rotation window

12. Choose Store secret.
13. To view the Rotation configuration for the secret, select the secret you created.
14. On the Secrets details page, scroll down to the Rotation configuration section. The Rotation status is Enabled and the Rotation schedule is cron(0 3 ? 1/1 2#2 *). The ARN of your Lambda function being used for your custom rotation is displayed.
    

    Figure 4: Rotation configuration of your secret

    You have now successfully stored a secret to meet your rotation requirements using the interactive Schedule expression builder. This option is easy to use with no prior knowledge of cron expressions required.

    In use case 2, we will be using schedule expression to directly enter a cron expression, to achieve a more complex rotation interval.

Use case 2: Set up custom rotation window using cron expression

The schedule expression option allows you to directly enter a cron expression using a string of six inputs. Cron expressions provide more flexibility when defining a rotation schedule which may not fit into the constraints of the Schedule expression builder feature.

Let’s suppose you have another secret in your organization which does not need to be rotated as frequently as the others. Consequently, you’ve been asked to set up rotation for the last Sunday of every quarter, during the off-peak hours of 1:00 AM to 4:00 AM UTC to avoid application downtime. Due to the complex nature of the requirements, you will need to use schedule expression option to write a cron job to achieve your use case.

Cron expressions consist of the following six required fields which are separated by a white space: Minutes, Hours, Day of month, Month, Day-of-week, and Year. Each required field has the following values using the syntax cron(fields), as shown in Table 1. Table 1: Secrets Manager supported cron expression fields and corresponding values

Table 1: Secrets Manager supported cron expression fields and corresponding values

Table 2: Description of supported wild cards for cron expression

As the use case is to set up a custom rotation window for the last Sunday of the quarter from 1:00 AM to 4:00 AM UTC, you’ll need to carry out the following steps:

To set up custom rotation using cron

1. To store a new secret in Secrets Manager, repeat steps 1-6 from Use case 1.
2. Once you’re on the Secret Rotation section of the Store a new secret screen, click Automatic rotation to enable rotation for the secret.
3. Under Rotation schedule, choose Schedule expression.
4. In the Schedule expression field box, enter cron(0 1 ? 3/3 1L *). Table 3 below explains the details for this expression.
   

   Fields	Values	Explanation
   Minutes	0	The use case does not have a specific minute requirement
   Hours	1	Ensures the rotation window starts from 1am UTC
   Day-of-month	?	The use case does not require rotation to occur on a specific date in the month
   Month	3/3	Sets rotation to occur on the last month in a quarter
   Day-of-week	1L	Ensures rotation occurs on the last Sunday of the month
   Year	*	Allows the rotation window pattern to be repeated yearly

   Table 3: Using cron expressions to achieve your rotation requirements
   

   Figure 5: Enable automatic rotation using the Schedule expression

   1. On the Rotation function section choose your Lambda rotation function from the dropdown menu.
   2. Choose Next.
   3. On the Secret review page, review the secret and scroll down to the Rotation schedule section. Confirm that the Rotation schedule and Next rotation date meet your requirements.
      

      Figure 6: Rotation schedule with a summary of your custom rotation window

   4. Choose Store.
   5. To view the Rotation configuration for this secret, select it from the Secrets page.
   6. On the Secrets details page, scroll down to the Rotation configuration section. The Rotation status is Enabled, the Rotation schedule is cron(0 1 ? 3/3 1L *) and the ARN of your Lambda function being used for your custom rotation is displayed.
      

Use case 3: Enabling a custom rotation window for an existing secret

If you already use AWS Secrets Manager as a way to store and rotate secrets for your organization, you might want to take advantage of custom-scheduled rotation on existing secrets. To meet your business needs, the secret must be rotated biweekly, every Saturday from 12am to 5am.

To enable a custom rotation window

1. On the Secrets page of the Secrets Manager console, choose the existing secret whose rotation you want to configure.
2. Scroll down to the Rotation configuration section of the Secret details page and choose Edit rotation.
   

   Figure 8: Rotation configuration section with a rotation status of Disabled

3. On the Edit rotation configuration pop-up window, turn on Automatic rotation to enable rotation for the secret.
4. Under Rotation Schedule choose Schedule expression builder (optionally, you can use the Schedule expression to create the custom rotation window, as described in Use case 2).
   1. For the Time unit choose Weeks, then enter a value of 2.
   2. For the Day of week choose Saturday from the dropdown menu.
   3. In the Start time field enter 00. This ensures rotation does not start until 00:00 AM UTC.
   4. In the Window duration field enter 5h. This provides Secrets Manager with a five-hour period to rotate the secret.
   5. For this example, keep the check box marked to rotate the secret immediately.
      

      Figure 9: Edit rotation configuration pop-up window

5. Under Rotation function, choose the lambda function which will be used to rotate the secret.
6. Choose Save.
7. On the Secrets details page, scroll down to the Rotation configuration section. The Rotation status is Enabled, the Rotation schedule is cron(0 00 ? * 7#2,7#4 *), and the ARN of the custom rotation Lambda function is visible.
   

   Figure 10: Rotation Configuration section with a rotation status of enabled

Summary

Regular rotation of secrets is a Secrets Manager best practice that helps you to meet compliance requirements (for example, for PCI DSS, which mandates the rotation of application secrets every 90 days) and to improve your security posture for database use and for any sort of credentials. The rotation window feature allows you to adhere to this best practice while still having the flexibility of choosing a rotation window that suits your organizational requirements. It also alleviates the need for applications to continuously refresh secret caches and manage retries for secrets that were rotated, as rotation will occur during your specified window when the application usage is low.

This blog post showed you how to create a secret and configure a rotation window using both the Schedule expression builder and the Schedule expression feature. The Use case examples show how each feature can be used to achieve different rotation requirements within an organization, from using the Schedule expression builder option to create your cron expression to using Schedule expression to achieve more specific requirements.

You can start using this feature through the AWS Secrets Manager console, AWS Command Line Interface (AWS CLI), AWS SDK, or AWS CloudFormation. To learn more about this feature, see the AWS Secrets Manager documentation.

If you have feedback about this blog post, submit comments in the Comments section below. If you have questions about this blog post, start a new thread on AWS Secrets Manager re:Post or contact AWS Support.

Want more AWS Security news? Follow us on Twitter.