How to create and retrieve secrets managed in AWS Secrets Manager using AWS CloudFormation templates

Updated November 15, 2018: We added information to make variables more clear in the sample template.

AWS Secrets Manager now integrates with AWS CloudFormation so you can create and retrieve secrets securely using CloudFormation. This integration makes it easier to automate provisioning your AWS infrastructure. For example, without any code changes, you can generate unique secrets for your resources with every execution of your CloudFormation template. This also improves the security of your infrastructure by storing secrets securely, encrypting automatically, and enabling rotation more easily.

Secrets Manager helps you protect the secrets needed to access your applications, services, and IT resources. In this post, I show how you can get the benefits of Secrets Manager for resources provisioned through CloudFormation. First, I describe the new Secrets Manager resource types supported in CloudFormation. Next, I show a sample CloudFormation template that launches a MySQL database on Amazon Relational Database Service (RDS). This template uses the new resource types to create, rotate, and retrieve the credentials (user name and password) of the database superuser required to launch the MySQL database.

Why use Secrets Manager with CloudFormation?

CloudFormation helps you model your AWS resources as templates and execute these templates to provision AWS resources at scale. Some AWS resources require secrets as part of the provisioning process. For example, to provision a MySQL database, you must provide the credentials for the database superuser. You can use Secrets Manager, the AWS dedicated secrets management service, to create and manage such secrets.

Secrets Manager makes it easier to rotate, manage, and retrieve database credentials, API keys, and other secrets throughout their lifecycle. You can now reference Secrets Manager in your CloudFormation templates to create unique secrets with every invocation of your template. By default, Secrets Manager encrypts these secrets with encryption keys that you own and control. Secrets Manager ensures the secret isn’t logged or persisted by CloudFormation by using a dynamic reference to the secret. You can configure Secrets Manager to rotate your secrets automatically without disrupting your applications. Secrets Manager offers built-in integrations for rotating credentials for all Amazon RDS databases and supports extensibility with AWS Lambda so you can meet your custom rotation requirements.

New Secrets Manager resource types supported in CloudFormation

1. AWS::SecretsManager::Secret — Create a secret and store it in Secrets Manager.
2. AWS::SecretsManager::ResourcePolicy — Create a resource-based policy and attach it to a secret. Resource-based policies enable you to control access to secrets.
3. AWS::SecretsManager::SecretTargetAttachment — Configure Secrets Manager to rotate the secret automatically.
4. AWS::SecretsManager::RotationSchedule — Define the Lambda function that will be used to rotate the secret.

How to use Secrets Manager in CloudFormation

Now that you’re familiar with the new Secrets Manager resource types supported in CloudFormation, I’ll show how you can use these in a CloudFormation template. I will use a sample template that creates a MySQL database in Amazon RDS and uses Secrets Manager to create the credentials for the superuser. The template also configures the secret to rotate every 30 days automatically.

1. Create a stack on the AWS CloudFormation console by copying the following sample template.

   
   ---
   Description: "How to create and retrieve secrets securely using an AWS CloudFormation template"
   Resources:
   
   # Create a secret with the username admin and a randomly generated password in JSON.  
     MyRDSInstanceRotationSecret:
       Type: AWS::SecretsManager::Secret
       Properties:
         Description: 'This is the secret for my RDS instance'
         GenerateSecretString:
           SecretStringTemplate: '{"username": "admin"}'
           GenerateStringKey: 'password'
           PasswordLength: 16
           ExcludeCharacters: '"@/\'
   
   
   
   # Create a MySQL database of size t2.micro.
   # The secret (username and password for the superuser) will be dynamically 
   # referenced. This ensures CloudFormation will not log or persist the resolved 
   # value. 
     MyDBInstance:
       Type: AWS::RDS::DBInstance
       Properties:
         AllocatedStorage: 20
         DBInstanceClass: db.t2.micro
         Engine: mysql
         MasterUsername: !Join ['', ['{{resolve:secretsmanager:', !Ref MyRDSInstanceRotationSecret, ':SecretString:username}}' ]]
         MasterUserPassword: !Join ['', ['{{resolve:secretsmanager:', !Ref MyRDSInstanceRotationSecret, ':SecretString:password}}' ]]
         BackupRetentionPeriod: 0
         DBInstanceIdentifier: 'rotation-instance'
   
   
   
   # Update the referenced secret with properties of the RDS database.
   # This is required to enable rotation. To learn more, visit our documentation
   # https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html
     SecretRDSInstanceAttachment:
       Type: AWS::SecretsManager::SecretTargetAttachment
       Properties:
         SecretId: !Ref MyRDSInstanceRotationSecret
         TargetId: !Ref MyDBInstance
         TargetType: AWS::RDS::DBInstance
   
   
   
   # Schedule rotating the secret every 30 days. 
   # Note, the first rotation is triggered immediately. 
   # This enables you to verify that rotation is configured appropriately.
   # Subsequent rotations are scheduled according to the configured rotation. 
   # This example assumes that you have previously created a Lambda function to rotate secrets of this type.
   # Replace <% replace-with-lambda-arn %> with the ARN of your rotation Lambda function.  
   # For details about rotation Lambdas, see:
   # https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html
     MySecretRotationSchedule:
       Type: AWS::SecretsManager::RotationSchedule
       DependsOn: SecretRDSInstanceAttachment
       Properties:
         SecretId: !Ref MyRDSInstanceRotationSecret
         # Remember to update this place holder with the ARN of your rotation lambda
         RotationLambdaARN: <% replace-with-lambda-arn %>
         RotationRules:
           AutomaticallyAfterDays: 30
   
   

2. Next, execute the stack.
    
   
   

   Figure 1: Execute the stack

3. After you execute the stack, open the RDS console to verify the database, rotation-instance, has been successfully created.
    
   
   

   Figure 2: Verify the database has been created

4. Open the Secrets Manager console and verify the stack successfully created the secret, MyRDSInstanceRotationSecret.
    
   
   

   Figure 3: Verify the stack successfully created the secret

Summary

I showed you how to create and retrieve secrets in CloudFormation. This improves the security of your infrastructure and makes it easier to automate infrastructure provisioning. To get started managing secrets, open the Secrets Manager console. To learn more, read How to Store, Distribute, and Rotate Credentials Securely with Secret Manager or refer to the Secrets Manager documentation.

If you have comments about this post, submit them in the Comments section below. If you have questions about anything in this post, start a new thread on the Secrets Manager forum or contact AWS Support.

Want more AWS Security news? Follow us on Twitter.