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.
Contents
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
For this tutorial, you need the following:
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
-
Go to Create a Secrets Manager secret for an Amazon RDS MySQL DB instance with AWS CloudFormation, and save the code to a new file. You can use either JSON or YAML.
To create the stack from the template
-
Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation
. -
Under Stacks, choose Create stack and then choose With new resources.
-
On the Create stack page, for Prepare template, choose Template is ready.
-
For Template source, choose Upload a template file.
-
Choose Choose file, and then choose the file you saved.
-
Choose Next.
-
On the Specify stack details page, name the stack
SecretsManagerRotationTutorial
, and then choose Next. -
On the Configure stack options page, choose Next.
-
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
Open the Amazon VPC console at https://console.aws.amazon.com/vpc/
. -
Choose Internet Gateways and then choose Create internet gateway.
-
On the Create internet gateway page, for Name tag, enter
SecretsManagerTutorialGateway
, and then choose Create internet gateway. -
On the igw-**** / SecretsManagerTutorialGateway page, in the green banner, choose Attach to a VPC.
-
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
Open the Amazon VPC console at https://console.aws.amazon.com/vpc/
. -
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. -
Choose Actions and then choose Edit routes.
-
On the Edit routes page, choose Add Route, and then do the following:
-
For Destination, enter
0.0.0.0/0
. -
For Target, choose Internet Gateway and then choose
igw-**** (SecretsManagerTutorialGateway)
. -
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
Open the Amazon VPC console at https://console.aws.amazon.com/vpc/
. -
Choose Security Groups and then choose Create Security Group.
-
For Security group name, enter
SecretsManagerTutorialAccess
. -
For Description, enter
Allows SSH access to bastion host
. -
For VPC, choose
vpc-**** (SecretsManagerTutorial)
. You might need to delete the prefilled text to see other choices. -
Under Inbound Rules, choose Add Rule.
-
For Inbound rule 1, do the following:
-
For Type, choose
SSH
. -
For Source, choose
My IP
.
-
-
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
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/
. -
Choose Instances and then choose Launch Instances.
-
On the Step 1 page, choose the default
Amazon Linux 2 AMI (HMV) Kernel 5.10
and then choose Select. -
On the Step 2 page, choose the default
t2.micro
and then choose Next: Configure Instance Details. -
On the Step 3 page, do the following:
-
For Network, choose
vpc-**** SecretsManagerTutorial
. -
For Auto-assign Public IP, choose
Enable
. -
Choose Next: Add Storage.
-
-
On the Step 4 page, choose Next: Add Tags.
-
On the Step 5 page, choose Add Tag.
For Key enter
Name
, and for Value enterSecretsManagerTutorialInstance
, and then choose Next: Configure Security Group. -
On the Step 6 page, for Assign a security group, choose Select an existing security group.
-
For Security group ID, choose the security groups with the names
default
andSecretsManagerTutorialAccess
, and then choose Review and Launch. -
On the Step 7 page, choose Launch.
-
In the Select an existing key pair dialog box, do the following:
-
Select Create a new key pair.
-
For Key pair name, enter
SecretsManagerTutorialKeyPair
. -
Choose Download Key Pair. You will use this private key file to connect to the instance in a later step.
-
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
-
In MySQL Workbench, next to MySQL Connections, choose the (+) button.
-
In the Setup New Connection dialog box, do the following:
-
For Connection Name, enter
SecretsManagerTutorial
. -
For Connection Method, choose
Standard TCP/IP over SSH
. -
On the Parameters tab, do the following:
-
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.
-
For SSH Username, enter
ec2-user
. -
For SSH Keyfile, choose the key pair file SecretsManagerTutorialKeyPair.pem you downloaded in the previous prerequisite.
-
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.
-
For Username, enter
admin
.
-
-
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
Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/
. -
Choose Secrets, and then choose the secret
SecretsManagerTutorialAdmin-****
. -
On the Secret details page, scroll down and choose Retrieve secret value.
-
In the Key/value table, copy the Secret value for
password
.
To test the credentials
-
In MySQL Workbench, choose the connection SecretsManagerTutorial.
-
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
Open the Amazon VPC console at https://console.aws.amazon.com/vpc/
. -
Under Endpoints, choose Create Endpoint.
-
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), choosecom.amazonaws.us-east-1.secretsmanager
. -
For VPC, choose
vpc**** (SecretsManagerTutorial)
. -
For Subnets, select all Availability Zones, and then for each one, choose a Subnet ID to include.
-
For Security groups, choose the default security group.
-
For Policy, choose
Full access
. -
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
Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/
. -
Open the secret SecretsManagerTutorialAdmin-a1b2c3d4e5f6, scroll down to Rotation configuration, and choose Edit rotation.
-
In the Edit rotation configuration dialog, turn on Automatic rotation.
-
For Rotation schedule, set a schedule of Days:
10
Days with Duration:2h
. Keep Rotate immediately selected. -
For Rotation function, do the following:
-
Choose Create a rotation function, and then for Lambda rotation function, enter
tutorial-single-user-rotation
. -
Secrets Manager will create a Lambda rotation function named SecretsManagertutorial-single-user-rotation.
-
For Use separate credentials, choose
No
.
-
-
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
Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/
. -
Choose Secrets, and then choose the secret
SecretsManagerTutorialAdmin-****
. -
On the Secret details page, scroll down and choose Retrieve secret value.
-
In the Key/value table, copy the Secret value for
password
.
To test the credentials
-
In MySQL Workbench, choose the connection SecretsManagerTutorial.
-
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:
-
Amazon EC2 instance. For instructions, see Terminate an instance.
-
Secrets Manager endpoint. For instructions, see Delete a VPC endpoint.
-
Internet gateway. First Detach an internet gateway from your VPC, then Delete an internet gateway.
-
AWS CloudFormation stack. For instructions, see Delete a stack.
Next steps
-
Learn how to retrieve secrets in your applications. See Retrieve secrets from AWS Secrets Manager.
-
Learn how to create a secret with automatic rotation using AWS CloudFormation, see AWS::SecretsManager::RotationSchedule in the AWS CloudFormation User Guide.
-
Learn about other rotation schedules. See Schedule expressions in Secrets Manager rotation.