AWS Secrets Manager Construct Library
import * as secretsmanager from '@aws-cdk/aws-secretsmanager';
Create a new Secret in a Stack
In order to have SecretsManager generate a new secret value automatically,
you can get started with the following:
example of creating a secret
The Secret
construct does not allow specifying the SecretString
property
of the AWS::SecretsManager::Secret
resource (as this will almost always
lead to the secret being surfaced in plain text and possibly committed to
your source control).
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:
const secret = secretsmanager.Secret.fromSecretAttributes(scope, 'ImportedSecret', {
secretArn: 'arn:aws:secretsmanager:<region>:<account-id-number>:secret:<secret-name>-<random-6-characters>',
encryptionKey,
});
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
, that removing a 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:
const role = new iam.Role(stack, 'SomeRole', { assumedBy: new iam.AccountRootPrincipal() });
const secret = new secretsmanager.Secret(stack, 'Secret');
secret.grantRead(role);
secret.grantWrite(role);
If, as in the following example, your secret was created with a KMS key:
const key = new kms.Key(stack, 'KMS');
const secret = new secretsmanager.Secret(stack, 'Secret', { encryptionKey: key });
secret.grantRead(role);
secret.grantWrite(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.
Rotating a Secret with a custom Lambda function
A rotation schedule can be added to a Secret using a custom Lambda function:
const fn = new lambda.Function(...);
const secret = new secretsmanager.Secret(this, 'Secret');
secret.addRotationSchedule('RotationSchedule', {
rotationLambda: fn,
automaticallyAfter: Duration.days(15)
});
See Overview of the Lambda Rotation Function on how to implement a Lambda Rotation Function.
Rotating database credentials
Define a SecretRotation
to rotate database credentials:
new SecretRotation(this, 'SecretRotation', {
application: SecretRotationApplication.MYSQL_ROTATION_SINGLE_USER,
secret: mySecret,
target: myDatabase,
vpc: myVpc,
});
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:
new SecretRotation(stack, 'SecretRotation', {
application: SecretRotationApplication.MYSQL_ROTATION_MULTI_USER,
secret: myUserSecret,
masterSecret: myMasterSecret,
target: myDatabase,
vpc: myVpc,
});
See also aws-rds where
credentials generation and rotation is integrated.