Set up automatic rotation for Amazon RDS, Amazon Aurora, Amazon Redshift, or Amazon DocumentDB secrets using the console

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. In Secrets Manager, you can set up automatic rotation for your database secrets.

Secrets Manager uses Lambda functions to rotate secrets. For an overview, see How rotation works.

Tip

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

To set up rotation using the console, you need to first choose a rotation strategy. Then you configure the secret for rotation, which creates a Lambda rotation function if you don't already have one. The console also sets permissions for the Lambda function execution role. The last step is to make sure that the Lambda rotation function can access both Secrets Manager and your database through the network.

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: Choose a rotation strategy and (optionally) create a superuser secret

For Amazon RDS, Amazon Redshift, and Amazon DocumentDB, Secrets Manager offers two rotation strategies:

Single user rotation strategy

This strategy updates credentials for one user in one secret. For Amazon RDS Db2 instances, because users can't change their own passwords, you must provide admin credentials in a separate secret. This is the simplest rotation strategy, and it is appropriate for most use cases. In particular, we recommend you use this strategy for credentials for one-time (ad hoc) or interactive users.

When the secret rotates, open database connections are not dropped. While rotation is happening, there is a short period of time between when the password in the database changes and when the secret is updated. During this time, there is a low risk of the database denying calls that use the rotated credentials. You can mitigate this risk with an appropriate retry strategy. After rotation, new connections use the new credentials.

Alternating users rotation strategy

This strategy updates credentials for two users in one secret. You create the first user, and during the first rotation, the rotation function clones it to create the second user. Every time the secret rotates, the rotation function alternates which user's password it updates. Because most users don't have permission to clone themselves, you must provide the credentials for a superuser in another secret. We recommend using the single-user rotation strategy when cloned users in your database don't have the same permissions as the original user, and for credentials for one-time (ad hoc) or interactive users.

This strategy is appropriate for databases with permission models where one role owns the database tables and a second role has permission to access the database tables. It is also appropriate for applications that require high availability. If an application retrieves the secret during rotation, the application still gets a valid set of credentials. After rotation, both user and user_clone credentials are valid. There is even less chance of applications getting a deny during this type of rotation than single user rotation. If the database is hosted on a server farm where the password change takes time to propagate to all servers, there is a risk of the database denying calls that use the new credentials. You can mitigate this risk with an appropriate retry strategy.

Secrets Manager creates the cloned user with the same permissions as the original user. If you change the original user's permissions after the clone is created, you must also change the cloned user's permissions.

Important

If you choose the alternating users strategy, you must Create a database secret and store database superuser credentials in it. You need a secret with superuser credentials because rotation clones the first user, and most users do not have that permission.

Step 2: Configure rotation and create a rotation function

Rotation functions for Amazon RDS (except Oracle and Db2) and Amazon DocumentDB automatically use Secure Socket Layer (SSL) or Transport Layer Security (TLS) to connect to your database, if it is available. Otherwise they use an unencrypted connection.

To turn on rotation for an Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret

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.

4. 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 Schedule expressions.

   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.

      If rotation fails, for example because Steps 3 and 4 are not yet completed, Secrets Manager retries the rotation process multiple times.

   5. Under Rotation function, do one of the following:

      • Choose Create a new Lambda function and enter a name for your new function. Secrets Manager adds SecretsManager to the beginning of the function name. Secrets Manager creates the function based on the appropriate template and sets the necessary permissions for the Lambda execution role.

      • Choose Use an existing Lambda function to reuse a rotation function you used for another secret. The rotation functions listed under Recommended VPC configurations have the same VPC and security group as the database, which helps the function access the database.

   6. For Rotation strategy, choose the Single user or Alternating users strategy. For more information, see Step 1: Choose a rotation strategy and (optionally) create a superuser secret.

5. Choose Save.

Step 3: (Optional) Set additional permissions conditions 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"
       }
   },

If the secret is encrypted with a KMS key other than the AWS managed key aws/secretsmanager, Secrets Manager grants 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.

To update your rotation function execution role

1. From the Lambda rotation function, choose Configuration, and then under Execution role, choose the Role name.

2. Follow the instructions at Modifying a role permissions policy to add a kms:EncryptionContext:SecretARN condition.

   "Condition": {
       "StringEquals": {
           "kms:EncryptionContext:SecretARN": "SecretARN"
       }
   },

Step 4: Set up network access for the rotation function

To be able to rotate a secret, the Lambda rotation function must be able to access both the secret and the database or service.

To access a secret

Your Lambda rotation function must be able to access a Secrets Manager endpoint. If your Lambda function can access the internet, then you can use a public endpoint. To find an endpoint, see AWS Secrets Manager endpoints.

If your Lambda function runs in a VPC that doesn't have internet access, we recommend you configure Secrets Manager service private endpoints within your VPC. Your VPC can then intercept requests addressed to the public regional endpoint and redirect them to the private endpoint. For more information, see VPC endpoint.

Alternatively, you can enable your Lambda function to access a Secrets Manager public endpoint by adding a NAT gateway or an internet gateway to your VPC, which allows traffic from your VPC to reach the public endpoint. This exposes your VPC to more risk because an IP address for the gateway can be attacked from the public Internet.

To access the database or service

If your database or service is running on an Amazon EC2 instance in a VPC, we recommend that you configure your Lambda function to run in the same VPC. Then the rotation function can communicate directly with your service. For more information, see Configuring VPC access.

To allow the Lambda function to access the database or service, you must make sure that the security groups attached to your Lambda rotation function allow outbound connections to the database or service. You must also make sure that the security groups attached to your database or service allow inbound connections from the Lambda rotation function.

For alternating users rotation where the superuser secret is managed by another AWS service, the Lambda rotation function must be able to call the service endpoint to get the database connection information. We recommend that you configure a VPC endpoint for the database service. For more information, see:

• Amazon RDS API and interface VPC endpoints in the Amazon RDS User Guide.

• Working with VPC endpoints in the Amazon Redshift Management Guide.

Step 5: (Optional) Customize the rotation function

In rare cases, you might want to customize the rotation function. 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.

For another example, 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.

To open your Lambda rotation function for editing

1. In the Secrets Manager console, choose your secret.

2. In the Rotation configuration section, under Lambda rotation function, choose your rotation function.

   The Lambda console opens.

   • To change the code in the function, scroll down to the Code source section.

   • For MySQL version 5.7 and higher, for alternating users rotation, to change the maximum username length, under Environment variables, change USERNAME_CHARACTER_LIMIT.

Next steps

See Troubleshoot AWS Secrets Manager rotation.