Get a secret or secret value from Secrets Manager - AWS CloudFormation
ConsiderationsPermissionsReference patternExamples

Get a secret or secret value from Secrets Manager

Secrets Manager is a service that allows you to securely store and manage secrets like database credentials, passwords, and third-party API keys. Using Secrets Manager, you can store and control access to these secrets centrally, so that you can replace hardcoded credentials in your code (including passwords), with an API call to Secrets Manager to retrieve the secret programmatically. For more information, see What is AWS Secrets Manager? in the AWS Secrets Manager User Guide.

To use entire secrets or secret values that are stored in Secrets Manager within your CloudFormation templates, you use secretsmanager dynamic references.

Considerations

When using secretsmanager dynamic references, there are a few important security considerations to keep in mind:

  • The secretsmanager dynamic reference can be used in all resource properties. Using the secretsmanager dynamic reference indicates that neither Secrets Manager nor CloudFormation logs should persist any resolved secret value. However, the secret value may show up in the service whose resource it's being used in. Review your usage to avoid leaking secret data.

  • Updating a secret in Secrets Manager doesn't automatically update the secret in CloudFormation. In order for CloudFormation to update a secretsmanager dynamic reference, you must perform a stack update that updates the resource containing the dynamic reference, either by updating the resource property that contains the secretsmanager dynamic reference, or updating another of the resource's properties.

    For example, suppose in your template you specify the MasterPassword property of an AWS::RDS::DBInstance resource to be a secretsmanager dynamic reference, and then create a stack from the template. You later update that secret's value in Secrets Manager, but don't update the AWS::RDS::DBInstance resource in your template. In this case, even if you perform a stack update, the secret value in the MasterPassword property isn't updated, and remains the previous secret value.

    Also, consider using Secrets Manager to automatically rotate the secret for a secured service or database. For more information, see Rotate AWS Secrets Manager secrets.

  • Dynamic references for secure values, such as secretsmanager, aren't currently supported in custom resources.

Permissions

To specify a secret stored in Secrets Manager, you must have permission to call GetSecretValue for the secret.

Reference pattern

To reference Secrets Manager secrets in your CloudFormation template, use the following secretsmanager reference pattern.

{{resolve:secretsmanager:secret-id:secret-string:json-key:version-stage:version-id}}
secret-id

The name or ARN of the secret.

To access a secret in your AWS account, you need only specify the secret name. To access a secret in a different AWS account, specify the complete ARN of the secret.

Required.

secret-string

The only supported value is SecretString. The default is SecretString.

json-key

The key name of the key-value pair whose value you want to retrieve. If you don't specify a json-key, CloudFormation retrieves the entire secret text.

This segment may not include the colon character ( :).

version-stage

The staging label of the version of the secret to use. Secrets Manager uses staging labels to keep track of different versions during the rotation process. If you use version-stage then don't specify version-id. If you don't specify either version-stage or version-id, then the default is the AWSCURRENT version.

This segment may not include the colon character ( :).

version-id

The unique identifier of the version of the secret to use. If you specify version-id, then don't specify version-stage. If you don't specify either version-stage or version-id, then the default is the AWSCURRENT version.

This segment may not include the colon character ( :).

Examples

Retrieving user name and password values from a secret

The following AWS::RDS::DBInstance example retrieves the user name and password values stored in the MySecret secret. The secret version retrieved is the version with the version stage value of AWSCURRENT.

JSON

{
    "MyRDSInstance": {
        "Type": "AWS::RDS::DBInstance",
        "Properties": {
            "DBName": "MyRDSInstance",
            "AllocatedStorage": "20",
            "DBInstanceClass": "db.t2.micro",
            "Engine": "mysql",
            "MasterUsername": "{{resolve:secretsmanager:MySecret:SecretString:username}}",
            "MasterUserPassword": "{{resolve:secretsmanager:MySecret:SecretString:password}}"
        }
    }
}

YAML

  MyRDSInstance:
    Type: 'AWS::RDS::DBInstance'
    Properties:
      DBName: MyRDSInstance
      AllocatedStorage: '20'
      DBInstanceClass: db.t2.micro
      Engine: mysql
      MasterUsername: '{{resolve:secretsmanager:MySecret:SecretString:username}}'
      MasterUserPassword: '{{resolve:secretsmanager:MySecret:SecretString:password}}'

Retrieving the entire SecretString

The following dynamic reference retrieves the SecretString for MySecret.

{{resolve:secretsmanager:MySecret}}

Alternatively:

{{resolve:secretsmanager:MySecret::::}}

Retrieving a value from a specific version of a secret

The following dynamic reference retrieves the password value for the AWSPREVIOUS version of MySecret.

{{resolve:secretsmanager:MySecret:SecretString:password:AWSPREVIOUS}}

Retrieving secrets from another AWS account

The following dynamic reference retrieves the SecretString for MySecret that's in another AWS account. You must specify the complete secret ARN to access secrets in another AWS account.

{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret}}

The following dynamic reference retrieves the password value for MySecret that's in another AWS account. You must specify the complete secret ARN to access secrets in another AWS account.

{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret:SecretString:password}}