Set up single user rotation for AWS Secrets Manager - AWS Secrets Manager

Set up single user rotation for AWS Secrets Manager

In this tutorial, you learn how to set up single user rotation for a secret that contains database admin credentials. Single user rotation is a rotation strategy where Secrets Manager updates a single user's credentials in both the secret and the database. For more information, see Rotation strategies.

A large part of this tutorial is setting up a realistic environment. To show you how rotation works, this tutorial uses an example Amazon RDS MySQL database. For security, the database is in a VPC that doesn't allow internet access. To connect to the database from your local computer through the internet, you use a bastion host, a server in the VPC that can connect to the database, but that also allows SSH connections from the internet. The bastion host in this tutorial is an Amazon EC2 instance, and the security groups for the instance prevent other types of connections.

As part of the prerequisites for the tutorial, you also create a secret that contains admin credentials for the database. The secret doesn't initially have rotation turned on. In this tutorial, you'll learn how to turn on automatic rotation.

Permissions

For the tutorial prerequisites, you need administrative permissions to your AWS account. In a production setting, it is a best practice to use different roles for each of the steps. For example, a role with database admin permissions would create the Amazon RDS database, and a role with network admin permissions would set up the VPC and security groups. For the tutorial steps, we recommend you continue using the same identity.

For information about how to set up permissions in a production environment, see Authentication and access control for AWS Secrets Manager.

Prerequisites

Prereq A: Amazon RDS database, Amazon VPC, and a Secrets Manager secret

Rather than creating these resources through the console, for this tutorial you use AWS CloudFormation with a provided template to create a CloudFormation stack. For more information about CloudFormation and templates, see AWS CloudFormation concepts.

To get the CloudFormation template

To create the stack from the template

  1. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

  2. Under Stacks, choose Create stack and then choose With new resources.

  3. On the Create stack page, for Prepare template, choose Template is ready.

  4. For Template source, choose Upload a template file.

  5. Choose Choose file, and then choose the file you saved.

  6. Choose Next.

  7. On the Specify stack details page, name the stack SecretsManagerRotationTutorial, and then choose Next.

  8. On the Configure stack options page, choose Next.

  9. On the Review page, choose Create stack.

CloudFormation opens the new stack in the console and begins creating the resources in the template. This process can take up to 30 minutes. You can see how far along it is in the process under Events. Choose the refresh button to update the events.

When the stack is complete, under Logical ID you see SecretsManagerRotationTutorial with Status CREATE_COMPLETE.

Prereq B: Internet gateway

For this tutorial, you need to create an internet gateway and attach it to the VPC to allow traffic to leave the VPC. You create a route in the route table so that traffic destined for outside the VPC is sent to the internet gateway. For more information, see Connect subnets to the internet using an internet gateway.

To create an internet gateway

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. Choose Internet Gateways and then choose Create internet gateway.

  3. On the Create internet gateway page, for Name tag, enterSecretsManagerTutorialGateway, and then choose Create internet gateway.

  4. On the igw-**** / SecretsManagerTutorialGateway page, in the green banner, choose Attach to a VPC.

  5. On the Attach to VPC page, for Available VPCs, choose vpc-**** - SecretsManagerTutorial, and then choose Attach internet gateway.

To add a route for the internet gateway

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. Choose Route tables, and then select the Route table ID associated with the VPC vpc-**** | SecretsManagerTutorial. You might need to scroll to see the column VPC in the table.

  3. Choose Actions and then choose Edit routes.

  4. On the Edit routes page, choose Add Route, and then do the following:

    1. For Destination, enter 0.0.0.0/0.

    2. For Target, choose Internet Gateway and then choose igw-**** (SecretsManagerTutorialGateway).

    3. Choose Save changes.

Prereq C: Security group

Create a security group to allow inbound SSH traffic to access a Amazon EC2 bastion host you'll create in a later step.

To allow SSH access to the bastion host

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. Choose Security Groups and then choose Create Security Group.

  3. For Security group name, enter SecretsManagerTutorialAccess.

  4. For Description, enter Allows SSH access to bastion host.

  5. For VPC, choose vpc-**** (SecretsManagerTutorial). You might need to delete the prefilled text to see other choices.

  6. Under Inbound Rules, choose Add Rule.

  7. For Inbound rule 1, do the following:

    1. For Type, choose SSH.

    2. For Source, choose My IP.

  8. Choose Create security group.

Prereq D: Amazon EC2 instance

To access the database in the VPC, you use a bastion host. The bastion host is also in the VPC, but it allows your local computer to connect to it with SSH. From the bastion host, you can access the database.

To create an EC2 instance for your bastion host

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. Choose Instances and then choose Launch Instances.

  3. On the Step 1 page, choose the default Amazon Linux 2 AMI (HMV) Kernel 5.10 and then choose Select.

  4. On the Step 2 page, choose the default t2.micro and then choose Next: Configure Instance Details.

  5. On the Step 3 page, do the following:

    1. For Network, choose vpc-**** SecretsManagerTutorial.

    2. For Auto-assign Public IP, choose Enable.

    3. Choose Next: Add Storage.

  6. On the Step 4 page, choose Next: Add Tags.

  7. On the Step 5 page, choose Add Tag.

    For Key enter Name, and for Value enter SecretsManagerTutorialInstance, and then choose Next: Configure Security Group.

  8. On the Step 6 page, for Assign a security group, choose Select an existing security group.

  9. For Security group ID, choose the security groups with the names default and SecretsManagerTutorialAccess, and then choose Review and Launch.

  10. On the Step 7 page, choose Launch.

  11. In the Select an existing key pair dialog box, do the following:

    1. Select Create a new key pair.

    2. For Key pair name, enter SecretsManagerTutorialKeyPair.

    3. Choose Download Key Pair. You will use this private key file to connect to the instance in a later step.

    4. Choose Launch Instances.

Prereq E: MySQL Workbench

To connect to the database, you use a MySQL client tool. In this tutorial, you use MySQL Workbench, a GUI-based application.

To install MySQL Workbench, see Download MySQL Workbench.

To connect to the database, you first create a connection configuration in MySQL Workbench. For the configuration, you need some information from both Amazon EC2 and Amazon RDS.

To create a database connection in MySQL Workbench

  1. In MySQL Workbench, next to MySQL Connections, choose the (+) button.

  2. In the Setup New Connection dialog box, do the following:

    1. For Connection Name, enter SecretsManagerTutorial.

    2. For Connection Method, choose Standard TCP/IP over SSH.

    3. On the Parameters tab, do the following:

      1. For SSH Hostname, enter the public IP address of the Amazon EC2 instance.

        You can find the IP address on the Amazon EC2 console by choosing the instance SecretsManagerTutorialInstance. Copy the IP address under Public IPv4 DNS.

      2. For SSH Username, enter ec2-user.

      3. For SSH Keyfile, choose the key pair file SecretsManagerTutorialKeyPair.pem you downloaded in the previous prerequisite.

      4. For MySQL Hostname, enter the Amazon RDS endpoint address.

        You can find the endpoint address on the Amazon RDS console by choosing the database instance secretsmanagertutorialdb. Copy the address under Endpoint.

      5. For Username, enter admin.

    4. Choose OK.

Step 1: Connect with original password

The first step is to check that the information in the secret contains valid credentials for the database.

To retrieve the password from the secret

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

  2. Choose Secrets, and then choose the secret SecretsManagerTutorialAdmin-****.

  3. On the Secret details page, scroll down and choose Retrieve secret value.

  4. In the Key/value table, copy the Secret value for password.

To test the credentials

  1. In MySQL Workbench, choose the connection SecretsManagerTutorial.

  2. In the Open SSH Connection dialog box, for Password, paste the password you retrieved from the secret, and then choose OK.

    The first time you connect, you might see a warning dialog box about the server fingerprint. Choose OK to continue.

If the credentials are valid, then MySQL Workbench opens to the design page for the database.

Step 2: Create a Secrets Manager endpoint

The next step is to create a Secrets Manager endpoint within the VPC. When you set up automatic rotation, Secrets Manager creates the Lambda rotation function within the VPC so that it has access to the database. The Lambda rotation function also calls Secrets Manager. By creating a Secrets Manager endpoint within the VPC, you ensure that calls from Lambda to Secrets Manager don't leave AWS infrastructure. Instead, they are routed to the Secrets Manager endpoint within the VPC. For more information, see Network access for the rotation function.

To create a Secrets Manager endpoint within the VPC

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. Under Endpoints, choose Create Endpoint.

  3. Scroll down to Services, enter secretsmanager to filter the list, and then select the Secrets Manager endpoint in your AWS Region. For example, in the US East (N. Virginia), choose com.amazonaws.us-east-1.secretsmanager.

  4. For VPC, choose vpc**** (SecretsManagerTutorial).

  5. For Subnets, select all Availability Zones, and then for each one, choose a Subnet ID to include.

  6. For Security groups, choose the default security group.

  7. For Policy, choose Full access.

  8. Choose Create endpoint.

Step 3: Rotate the secret

Now you are ready to turn on rotation. You start an immediate rotation, so Secrets Manager rotates the secret immediately when you save the secret. You also turn on automatic rotation, so the secret is rotated every 10 days between midnight and 2:00 AM UTC.

To turn on automatic rotation

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

  2. Open the secret SecretsManagerTutorialAdmin-a1b2c3d4e5f6, scroll down to Rotation configuration, and choose Edit rotation.

  3. In the Edit rotation configuration dialog, turn on Automatic rotation.

  4. For Rotation schedule, set a schedule of Days: 10 Days with Duration: 2h. Keep Rotate immediately selected.

  5. For Rotation function, do the following:

    1. Choose Create a rotation function, and then for Lambda rotation function, enter tutorial-single-user-rotation.

    2. Secrets Manager will create a Lambda rotation function named SecretsManagertutorial-single-user-rotation.

    3. For Use separate credentials, choose No.

  6. Choose Save.

    Secrets Manager returns to the the secret details page. Secrets Manager uses CloudFormation to create resources such as the Lambda rotation function and an execution role that runs the Lambda function. At the top of the secret details page, you can see the status of the CloudFormation resources. When CloudFormation finishes deploying the resources, the banner changes to Secret scheduled for rotation. Now Secrets Manager begins the first rotation.

Step 4: Test the rotated password

After the first secret rotation, which might take a few seconds, you can check that the secret still contains valid credentials. The password in the secret has changed from the original credentials.

To retrieve the new password from the secret

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

  2. Choose Secrets, and then choose the secret SecretsManagerTutorialAdmin-****.

  3. On the Secret details page, scroll down and choose Retrieve secret value.

  4. In the Key/value table, copy the Secret value for password.

To test the credentials

  1. In MySQL Workbench, choose the connection SecretsManagerTutorial.

  2. In the Open SSH Connection dialog box, for Password, paste the password you retrieved from the secret, and then choose OK.

    If the credentials are valid, then MySQL Workbench opens to the design page for the database.

This shows that the secret rotation is successful. The updated password in the secret is a valid password to connect to the database. You have finished setting up automatic rotation, and the next rotation will happen in 10 days.

Step 5: Clean up resources

If you want to try another rotation strategy, alternating users rotation, skip cleaning up resources and go to Set up alternating users rotation for AWS Secrets Manager.

Otherwise, to avoid potential charges, and to remove the EC2 instance that has access to the internet, delete the following resources you created in this tutorial:

Next steps