AWS Secrets Manager
User Guide

Enabling Rotation for an Amazon DocumentDB Secret

You can enable rotation for a secret with credentials for a Amazon DocumentDB database by using the AWS Secrets Manager console, the AWS CLI, or one of the AWS SDKs.

Warning

Enabling rotation causes the secret to immediately rotate once when you save the secret. Before you enable rotation, be sure to update all of your applications using the secret credentials to retrieve the secret from Secrets Manager. The original credentials may be unusable after the initial rotation. Any applications you fail to update break as soon as the old credentials become invalid.

Prerequisites: Network Requirements to Enable Rotation

To successfully enable rotation, you must have your network environment configured correctly.

  • The Lambda function must be able to communicate with the database. If you run your DocumentDB database instance in a VPC, we recommend configuring your Lambda function to run in the same VPC. By doing so, you enable direct connectivity between the rotation function and your service. To configure this, on the Lambda function details page, scroll down to the Network section and select the VPC from the list to match the one for your instance. You must also be sure the EC2 security groups attached to your instance enable communication between the instance and Lambda.

  • The Lambda function must be able to communicate with the Secrets Manager service endpoint. If your Lambda rotation function can access the Internet, either because you haven't configured the function to run in a VPC, or because the VPC has an attached NAT gateway, then you can use any of the available public endpoints for Secrets Manager. Alternatively, if your Lambda function is configured to run in a VPC without any internet access, then you can configure the VPC with a private Secrets Manager service endpoint.

To enable and configure rotation for a Amazon DocumentDB secret

Follow the steps under one of the following tabs:

Using the AWS Management ConsoleUsing the AWS CLI or SDK Operations
Using the AWS Management Console

Minimum permissions

To enable and configure rotation in the console, you must have the permissions provided by the following managed policies:

  • SecretsManagerReadWrite – Provides all of the Secrets Manager, Lambda, and AWS CloudFormation permissions.

  • IAMFullAccess – Provides the IAM permissions required to create a role and attach a permission policy to it.

  1. Sign in to the AWS Secrets Manager console at https://console.aws.amazon.com/secretsmanager/.

  2. Choose the name of the secret to enable rotation.

  3. In the Configure automatic rotation section, select Enable automatic rotation. This enables the other controls in this section.

  4. For Select rotation interval, select one of the predefined values—or choose Custom, and then type the number of days you want between rotations. If you're rotating your secret to meet compliance requirements, then we recommend you set this value to at least 1 day less than the compliance-mandated interval.

    Secrets Manager schedules the next rotation when the previous one is complete. Secrets Manager schedules the date by adding the rotation interval (number of days) to the actual date of the last rotation. The service chooses the hour within that 24-hour date window randomly. The minute is also chosen somewhat randomly, but is weighted towards the top of the hour and influenced by a variety of factors that help distribute load.

    Note

    If you use the Lambda function provided by Secrets Manager to alternate between two users (the console uses this template if you selected the second "master secret" option in the next step), then you should set your rotation period to one-half of your compliance-specified minimum interval. The old credentials are still available (if not actively used) for one additional rotation cycle. Secrets Manager invalidates the old credentials only after the user updates with a new password after the second rotation.

    If you modify the rotation function to immediately invalidate the old credentials after the new secret becomes active, then you can extend the rotation interval to your full compliance-mandated minimum. Leaving the old credentials active for one additional cycle with the AWSPREVIOUS staging label provides a "last known good" set of credentials you can use for fast recovery. If something happens that breaks the current credentials, you can simply move the AWSCURRENT staging label to the version with the AWSPREVIOUS label. Then your customers should be able to access the resource again. For more information, see Rotating AWS Secrets Manager Secrets by Alternating Between Two Existing Users.

  5. Select one of the following options:

    • You want to create a new Lambda rotation function

      1. Select Create a new Lambda function to perform rotation.

      2. For Lambda function name, enter the name you want to assign to the Lambda function that Secrets Manager created for you.

      3. Specify the secret with credentials for the rotation function. The credentials must have permissions to update the user name and password on the protected database.

        • Use this secret: Select this option if the credentials in this secret have permission in the database to change the password. Selecting this option causes Secrets Manager to create a Lambda function that rotates secrets with a single user getting only the password changed with each rotation.

          Note

          This option is the "lower availability" option, because sign-in failures can occur between the moment when Secrets Manager removes the old password by the rotation and the moment when Secrets Manager allows the updated password to become accessible as a new version of the secret. This time window should be very short, on the order of a few seconds or less, but it can happen.

          If you choose the Use this secret option, ensure that your client applications signing in with the secret use an appropriate "backoff and retry with jitter" strategy in code. A real failure should be reported only if signing in fails several times over a longer period of time.

        • Use a secret that I have previously stored in AWS Secrets Manager: Select this option if the credentials in the current secret don't have permissions to update, or if you require high availability for the secret. To select this option, you must create a separate "master" secret with credentials with permissions to update the secret credentials. Then select the master secret from the list. Selecting this option causes Secrets Manager to create a Lambda function that rotates secrets by creating a new user and password with each rotation, and deprecating the old user.

          Note

          This is the "high availability" option because the old version of the secret continues to operate and handle service requests while the new version is prepared and tested. Secrets Manager doesn't delete the old version until after the clients switch to the new version. There's no downtime while changing between versions.

          This option requires the Lambda function to clone the permissions of the original user and apply them to the new user in each rotation.

    • You want to use a Lambda function you already created for another secret

      1. Select Use an existing Lambda function to perform rotation.

      2. Select the Lambda function from the list.

      3. Specify the type of rotation function you selected:

        • Single-user rotation: A rotation function for a secret that stores credentials for a user with permissions to change their password. This is the type of function created when you select the option Use this secret when you create a function.

        • Multi-user rotation: A rotation function for a secret that stores credentials for a user that can't change their password. The function requires a separate master secret that stores credentials for a user with permission to change the credentials for this secret's user. This is the type of function created when you select the option Use a secret that I have previously stored in AWS Secrets Manager when you create a function.

      4. If you specified the second "master secret" option, then you must also select the secret that can provide the master user's credentials. The credentials in the master secret must have permission to update the credentials stored in this secret.

  6. Select Save to store your changes and to trigger the initial rotation of the secret.

  7. If you opted to rotate your secret with a separate master secret, then you must manually grant your Lambda rotation function permission to access the master secret. Follow these instructions:

    1. When rotation configuration completes, the following message may appear at the top of the page:

      Your secret <secret name> has been successfully stored and secret rotation is enabled. To finish configuring rotation, you need to provide the role permissions to access the value of the secret <Amazon Resource Name (ARN) of your master secret>.

      If this appears, then you must manually modify the policy for the role to grant the rotation function secretsmanager:GetSecretValue permission to access the master secret. Secrets Manager can't do this for you for security reasons. Rotation of the secret fails until you complete the following steps if it can't access the master secret.

    2. Copy the Amazon Resource Name (ARN) from the message to your clipboard.

    3. Select the link on the word "role" in the message. This opens the IAM console to the role details page for the role attached to the Lambda rotation function that Secrets Manager created for you.

    4. On the Permissions tab, select Add inline policy, and then set the following values:

      • For Service, select Secrets Manager.

      • For Actions, select GetSecretValue.

      • For Resources, select Add ARN next to the secret resource type entry.

      • In the Add ARN(s) dialog box, paste the ARN of the master secret that you copied previously.

    5. Select Review policy, and then Select Create policy.

      Note

      As an alternative to using the Visual Editor as described in the previous steps, you can paste the following statement into an existing or new policy:

      { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "<ARN of the master secret>" }
    6. Return to the AWS Secrets Manager console.

If you don't have an ARN for a Lambda function assigned to the secret, Secrets Manager creates the function, assigns all required permissions, and configures it to work with your database. Secrets Manager counts down the number of days specified in the rotation interval. When Secrets Manager reaches zero, Secrets Manager rotates the secret again and resets the interval for the next cycle. This continues until you disable rotation.

Using the AWS CLI or SDK Operations

Minimum permissions

To enable and configure rotation in the console, you must have the permissions provided by the following managed policies:

  • SecretsManagerReadWrite – Provides all of the Secrets Manager, Lambda, and AWS CloudFormation permissions.

  • IAMFullAccess – Provides the IAM permissions required to create a role and attach a permission policy to it.

You can use the following Secrets Manager commands to configure rotation for an existing secret for a supported Amazon RDS database:

You also need to use commands from AWS CloudFormation and AWS Lambda. For more information about the commands that follow, see the documentation for those services.

Important

The exact format of the secret value that you must use in your secret is determined by the rotation function you want to use with this secret. For the details of what each rotation function requires for the secret value, see the Expected SecretString Value entry under the relevant rotation function at AWS Templates You Can Use to Create Lambda Rotation Functions .

To create a Lambda rotation function by using an AWS Serverless Application Repository template

The following example of a AWS CLI session that performs the equivalent of the console-based rotation configuration described in the Using the AWS Management Console tab. You create the function by using an AWS CloudFormation change set. Then you configure the resulting function with the required permissions. Finally, you configure the secret with the ARN of the completed function, and rotate once to test it.

The following example uses the generic template, so it uses the last ARN shown earlier.

If your database or service resides in a VPC provided by Amazon VPC, then you must include the fourth of the following commands to configure the function to communicate with that VPC. If you don't have a VPC, then you can skip that command.

Also, if your VPC doesn't have access to the public internet, then you must configure your VPC with a private service endpoint for Secrets Manager. The fifth of the following commands does that.

The first command sets up an AWS CloudFormation change set based on the template provided by Secrets Manager.

You use the --application-id parameter to specify which template to use. The value is the ARN of the template. For the list of templates provided by AWS and the ARNs, see AWS Templates You Can Use to Create Lambda Rotation Functions .

The templates also require additional parameters provided with --parameter-overrides, as shown in the example that follows. Secrets Manager requires this parameter to pass two pieces of information as Name and Value pairs to the template that affects Secrets Manager creates the rotation function:

  • endpoint – The URL of the service endpoint you want the rotation function to query. Typically, this is https://secretsmanager.region.amazonaws.com.

  • functionname – The name of the completed Lambda rotation function created by this process.

$ aws serverlessrepo create-cloud-formation-change-set \ --application-id arn:aws:serverlessrepo:us-east-1:297356227824:applications/SecretsManagerRotationTemplate \ --parameter-overrides '[{"Name":"endpoint","Value":"https://secretsmanager.region.amazonaws.com"},{"Name":"functionName","Value":"MyLambdaRotationFunction"}]' \ --stack-name MyLambdaCreationStack { "ApplicationId": "arn:aws:serverlessrepo:us-west-2:297356227824:applications/SecretsManagerRDSMySQLRotationSingleUser", "ChangeSetId": "arn:aws:cloudformation:us-west-2:123456789012:changeSet/EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE/EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE", "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/aws-serverless-repository-MyLambdaCreationStack/EXAMPLE3-90ab-cdef-fedc-ba987EXAMPLE" }

The next command runs the change set that you just created. The change-set-name parameter comes from the ChangeSetId output of the previous command. This command produces no output.

$ aws cloudformation execute-change-set --change-set-name arn:aws:cloudformation:us-west-2:123456789012:changeSet/EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE/EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE

The following command grants the Secrets Manager service permission to call the function on your behalf. The output shows the permission added to the role's trust policy.

$ aws lambda add-permission \ --function-name MyLambdaRotationFunction \ --principal secretsmanager.amazonaws.com \ --action lambda:InvokeFunction \ --statement-id SecretsManagerAccess { "Statement": "{\"Sid\":\"SecretsManagerAccess\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"secretsmanager.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:us-west-2:123456789012:function:MyLambdaRotationFunction\"}" }

Secrets Manager requires the following command only if you run your database in a VPC. If it isn't, skip this command. Look up the VPC information for your Amazon RDS DB instance by using either the Amazon RDS console, or by using the aws rds describe-instances CLI command. Then add that information in the following command and run it.

$ aws lambda update-function-configuration \ --function-name arn:aws:lambda:us-west-2:123456789012:function:MyLambdaRotationFunction \ --vpc-config SubnetIds=<COMMA SEPARATED LIST OF VPC SUBNET IDS>,SecurityGroupIds=<COMMA SEPARATED LIST OF SECURITY GROUP IDs>

If the VPC with your database instance and Lambda rotation function doesn't have Internet access, then you must configure the VPC with a private service endpoint for Secrets Manager. This enables the rotation function to access Secrets Manager at an endpoint within the VPC.

$ aws ec2 create-vpc-endpoint --vpc-id <VPC ID> / --vpc-endpoint-type Interface / --service-name com.amazonaws.<region>.secretsmanager / --subnet-ids <COMMA SEPARATED LIST OF VPC SUBNET IDS> / --security-group-ids <COMMA SEPARATED LIST OF SECURITY GROUP IDs> / --private-dns-enabled

If you created a function using a template that requires a master secret, then you must also add the following statement to the function role policy. This grants permission to the rotation function to retrieve the secret value for the master secret. For complete instructions, see Granting a Rotation Function Permission to Access a Separate Master Secret.

{ "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager:region:123456789012:secret:MyDatabaseMasterSecret", "Effect": "Allow" },

Finally, you can apply the rotation configuration to your secret and perform the initial rotation.

$ aws secretsmanager rotate-secret \ --secret-id production/MyAwesomeAppSecret \ --rotation-lambda-arn arn:aws:lambda:us-west-2:123456789012:function:aws-serverless-repository-SecretsManagerRDSMySQLRo-10WGBDAXQ6ZEH \ --rotation-rules AutomaticallyAfterDays=7

We recommend that even if you want to create your own Lambda rotation function, you should follow the preceding steps that use the SecretsManagerRotationTemplate AWS CloudFormation template as it allows Secrets Manager to set up most of the permissions and configuration settings for you.