AWS Secrets Manager
User Guide

Enabling Rotation for an Amazon Redshift Secret

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

Warning

Enabling rotation causes the secret to rotate once immediately when you save the secret. Before you enable rotation, be sure you update all of your applications using this secret's credentials to retrieve the secret from Secrets Manager. The original credentials might not be usable after the initial rotation. Any applications that 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 Amazon Redshift service. If you run your Amazon Redshift cluster in a VPC, we recommend that you configure your Lambda function to run in the same VPC. This enables 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 make sure that the EC2 security groups attached to your cluster enable communication between the cluster 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 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 supported Amazon Redshift cluster 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. Select the name of the secret that you want to enable rotation for.

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

  4. For Select rotation interval, choose one of the predefined values—or choose Custom, and then enter the number of days between rotations. If you're rotating your secret to meet compliance requirements, then we recommend that 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 that's provided by Secrets Manager to alternate between two users (the console uses this template if you choose 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 only invalidates the old credentials only after the password updates for the user 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 that 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 that has 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. Choose 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 creates for you.

      3. Specify the secret with credentials that the rotation function can use. They must have permissions to update the user name and password on the protected service.

        • Use this secret: Select this option if the credentials in this secret have permission in the service to change their own password. Selecting this option causes Secrets Manager to create a Lambda function that rotates secrets with a single user that gets only its 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 the updated password becomes 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 select the Use this secret option, be sure 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 credentials of the secret. 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 Secrets Manager prepares and tests the new version. 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 drop-down list.

      3. Specify what type of rotation function you chose:

        • Single-user rotation: A rotation function for a secret that stores credentials for a user with permissions to change their password. Secrets Manager creates this type of function 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 without permission to change their password. The function requires a separate master secret that stores credentials for a user with permission to change the credentials for the user of this secret. Secrets Manager creates this type of function when you select the option Use a secret that I have previously stored in AWS Secrets Manager.

      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 might 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. If Secrets Manager can't access the master secret, rotation of the secret fails until you complete the following steps.

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

    3. Click 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. Choose Review policy, and then choose 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 service. Secrets Manager counts down the number of days specified in the rotation interval. When it 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 Amazon Redshift:

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 type of rotation function determines the exact format of the secret value that you must use in your 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 is an example AWS CLI session that performs the equivalent of the console-based rotation configuration that's 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 that was shown earlier.

If your 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 no VPC is involved, 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 their 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 affect the creation of the rotation function:

  • endpoint – The URL of the service endpoint that you want the rotation function to query, for example, 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 displays 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\"}" }

If you run your service in a VPC, Secrets Manager requires the following command. If not, skip this command. Look up the VPC information for your Amazon Redshift cluster by using either the Amazon RDS console, or by using the aws rds describe-instances CLI command. Then put 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 service 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's 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 for Amazon Redshift, you should follow the preceding steps that use the SecretsManagerRotationTemplate AWS CloudFormation template. Lambda alows Secrets Manager to set up most of the permissions and configuration settings for you.