AWS Secrets Manager Construct Library
import aws_cdk.aws_secretsmanager as secretsmanager
Create a new Secret in a Stack
To have SecretsManager generate a new secret value automatically, follow this example:
# vpc: ec2.IVpc
instance1 = rds.DatabaseInstance(self, "PostgresInstance1",
engine=rds.DatabaseInstanceEngine.POSTGRES,
# Generate the secret with admin username `postgres` and random password
credentials=rds.Credentials.from_generated_secret("postgres"),
vpc=vpc
)
# Templated secret with username and password fields
templated_secret = secretsmanager.Secret(self, "TemplatedSecret",
generate_secret_string=secretsmanager.SecretStringGenerator(
secret_string_template=JSON.stringify({"username": "postgres"}),
generate_string_key="password",
exclude_characters="/@\""
)
)
# Using the templated secret as credentials
instance2 = rds.DatabaseInstance(self, "PostgresInstance2",
engine=rds.DatabaseInstanceEngine.POSTGRES,
credentials={
"username": templated_secret.secret_value_from_json("username").to_string(),
"password": templated_secret.secret_value_from_json("password")
},
vpc=vpc
)
If you need to use a pre-existing secret, the recommended way is to manually
provision the secret in AWS SecretsManager and use the Secret.fromSecretArn
or Secret.fromSecretAttributes
method to make it available in your CDK Application:
# encryption_key: kms.Key
secret = secretsmanager.Secret.from_secret_attributes(self, "ImportedSecret",
secret_arn="arn:aws:secretsmanager:<region>:<account-id-number>:secret:<secret-name>-<random-6-characters>",
# If the secret is encrypted using a KMS-hosted CMK, either import or reference that key:
encryption_key=encryption_key
)
SecretsManager secret values can only be used in select set of properties. For the list of properties, see the CloudFormation Dynamic References documentation.
A secret can set RemovalPolicy
. If it set to RETAIN
, removing that secret will fail.
Grant permission to use the secret to a role
You must grant permission to a resource for that resource to be allowed to
use a secret. This can be achieved with the Secret.grantRead
and/or Secret.grantWrite
method, depending on your need:
role = iam.Role(self, "SomeRole", assumed_by=iam.AccountRootPrincipal())
secret = secretsmanager.Secret(self, "Secret")
secret.grant_read(role)
secret.grant_write(role)
If, as in the following example, your secret was created with a KMS key:
# role: iam.Role
key = kms.Key(self, "KMS")
secret = secretsmanager.Secret(self, "Secret", encryption_key=key)
secret.grant_read(role)
secret.grant_write(role)
then Secret.grantRead
and Secret.grantWrite
will also grant the role the
relevant encrypt and decrypt permissions to the KMS key through the
SecretsManager service principal.
The principal is automatically added to Secret resource policy and KMS Key policy for cross account access:
other_account = iam.AccountPrincipal("1234")
key = kms.Key(self, "KMS")
secret = secretsmanager.Secret(self, "Secret", encryption_key=key)
secret.grant_read(other_account)
Using a Custom Lambda Function
A rotation schedule can be added to a Secret using a custom Lambda function:
import aws_cdk.aws_lambda as lambda_
# fn: lambda.Function
secret = secretsmanager.Secret(self, "Secret")
secret.add_rotation_schedule("RotationSchedule",
rotation_lambda=fn,
automatically_after=Duration.days(15),
rotate_immediately_on_update=False
)
Note: The required permissions for Lambda to call SecretsManager and the other way round are automatically granted based on AWS Documentation as long as the Lambda is not imported.
See Overview of the Lambda Rotation Function on how to implement a Lambda Rotation Function.
Using a Hosted Lambda Function
Use the hostedRotation
prop to rotate a secret with a hosted Lambda function:
secret = secretsmanager.Secret(self, "Secret")
secret.add_rotation_schedule("RotationSchedule",
hosted_rotation=secretsmanager.HostedRotation.mysql_single_user()
)
Hosted rotation is available for secrets representing credentials for MySQL, PostgreSQL, Oracle, MariaDB, SQLServer, Redshift and MongoDB (both for the single and multi user schemes).
When deployed in a VPC, the hosted rotation implements ec2.IConnectable
:
# my_vpc: ec2.IVpc
# db_connections: ec2.Connections
# secret: secretsmanager.Secret
my_hosted_rotation = secretsmanager.HostedRotation.mysql_single_user(vpc=my_vpc)
secret.add_rotation_schedule("RotationSchedule", hosted_rotation=my_hosted_rotation)
db_connections.allow_default_port_from(my_hosted_rotation)
Use the excludeCharacters
option to customize the characters excluded from
the generated password when it is rotated. By default, the rotation excludes
the same characters as the ones excluded for the secret. If none are defined
then the following set is used: % +~
#$&*()|[]{}:;<>?!’/@”`.
Rotating database credentials
Define a SecretRotation
to rotate database credentials:
# my_secret: secretsmanager.Secret
# my_database: ec2.IConnectable
# my_vpc: ec2.Vpc
secretsmanager.SecretRotation(self, "SecretRotation",
application=secretsmanager.SecretRotationApplication.MYSQL_ROTATION_SINGLE_USER, # MySQL single user scheme
secret=my_secret,
target=my_database, # a Connectable
vpc=my_vpc, # The VPC where the secret rotation application will be deployed
exclude_characters=" %+:;{}"
)
The secret must be a JSON string with the following format:
{
"engine": "<required: database engine>",
"host": "<required: instance host name>",
"username": "<required: username>",
"password": "<required: password>",
"dbname": "<optional: database name>",
"port": "<optional: if not specified, default port will be used>",
"masterarn": "<required for multi user rotation: the arn of the master secret which will be used to create users/change passwords>"
}
For the multi user scheme, a masterSecret
must be specified:
# my_user_secret: secretsmanager.Secret
# my_master_secret: secretsmanager.Secret
# my_database: ec2.IConnectable
# my_vpc: ec2.Vpc
secretsmanager.SecretRotation(self, "SecretRotation",
application=secretsmanager.SecretRotationApplication.MYSQL_ROTATION_MULTI_USER,
secret=my_user_secret, # The secret that will be rotated
master_secret=my_master_secret, # The secret used for the rotation
target=my_database,
vpc=my_vpc
)
By default, any stack updates will cause AWS Secrets Manager to rotate a secret immediately. To prevent this behavior and wait until the next scheduled rotation window specified via the automaticallyAfter
property, set the rotateImmediatelyOnUpdate
property to false:
# my_user_secret: secretsmanager.Secret
# my_master_secret: secretsmanager.Secret
# my_database: ec2.IConnectable
# my_vpc: ec2.Vpc
secretsmanager.SecretRotation(self, "SecretRotation",
application=secretsmanager.SecretRotationApplication.MYSQL_ROTATION_MULTI_USER,
secret=my_user_secret, # The secret that will be rotated
master_secret=my_master_secret, # The secret used for the rotation
target=my_database,
vpc=my_vpc,
automatically_after=Duration.days(7),
rotate_immediately_on_update=False
)
See also aws-rds where credentials generation and rotation is integrated.
Importing Secrets
Existing secrets can be imported by ARN, name, and other attributes (including the KMS key used to encrypt the secret). Secrets imported by name should use the short-form of the name (without the SecretsManager-provided suffix); the secret name must exist in the same account and region as the stack. Importing by name makes it easier to reference secrets created in different regions, each with their own suffix and ARN.
secret_complete_arn = "arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret-f3gDy9"
secret_partial_arn = "arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret" # No Secrets Manager suffix
encryption_key = kms.Key.from_key_arn(self, "MyEncKey", "arn:aws:kms:eu-west-1:111111111111:key/21c4b39b-fde2-4273-9ac0-d9bb5c0d0030")
my_secret_from_complete_arn = secretsmanager.Secret.from_secret_complete_arn(self, "SecretFromCompleteArn", secret_complete_arn)
my_secret_from_partial_arn = secretsmanager.Secret.from_secret_partial_arn(self, "SecretFromPartialArn", secret_partial_arn)
my_secret_from_name = secretsmanager.Secret.from_secret_name_v2(self, "SecretFromName", "MySecret")
my_secret_from_attrs = secretsmanager.Secret.from_secret_attributes(self, "SecretFromAttributes",
secret_complete_arn=secret_complete_arn,
encryption_key=encryption_key
)
Replicating secrets
Secrets can be replicated to multiple regions by specifying replicaRegions
:
# my_key: kms.Key
secretsmanager.Secret(self, "Secret",
replica_regions=[secretsmanager.ReplicaRegion(
region="eu-west-1"
), secretsmanager.ReplicaRegion(
region="eu-central-1",
encryption_key=my_key
)
]
)
Alternatively, use addReplicaRegion()
:
secret = secretsmanager.Secret(self, "Secret")
secret.add_replica_region("eu-west-1")
Creating JSON Secrets
Sometimes it is necessary to create a secret in SecretsManager that contains a JSON object. For example:
{
"username": "myUsername",
"database": "foo",
"password": "mypassword"
}
In order to create this type of secret, use the secretObjectValue
input prop.
# stack: Stack
user = iam.User(self, "User")
access_key = iam.AccessKey(self, "AccessKey", user=user)
secretsmanager.Secret(self, "Secret",
secret_object_value={
"username": SecretValue.unsafe_plain_text(user.user_name),
"database": SecretValue.unsafe_plain_text("foo"),
"password": access_key.secret_access_key
}
)
In this case both the username
and database
are not a Secret
so SecretValue.unsafePlainText
needs to be used.
This means that they will be rendered as plain text in the template, but in this case neither of those
are actual “secrets”.