Namespace Amazon.CDK.AWS.SecretsManager
AWS Secrets Manager Construct Library
---AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.
For more information on how to migrate, see the Migrating to AWS CDK v2 guide.
using Amazon.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:
// Default secret
var secret = new Secret(this, "Secret");
// Using the default secret
// Using the default secret
new User(this, "User", new UserProps {
Password = secret.SecretValue
});
// Templated secret
var templatedSecret = new Secret(this, "TemplatedSecret", new SecretProps {
GenerateSecretString = new SecretStringGenerator {
SecretStringTemplate = JSON.Stringify(new Dictionary<string, string> { { "username", "user" } }),
GenerateStringKey = "password"
}
});
// Using the templated secret
// Using the templated secret
new User(this, "OtherUser", new UserProps {
UserName = templatedSecret.SecretValueFromJson("username").ToString(),
Password = templatedSecret.SecretValueFromJson("password")
});
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:
Key encryptionKey;
var secret = Secret.FromSecretAttributes(this, "ImportedSecret", new SecretAttributes {
SecretArn = "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:
EncryptionKey = 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:
var role = new Role(this, "SomeRole", new RoleProps { AssumedBy = new AccountRootPrincipal() });
var secret = new Secret(this, "Secret");
secret.GrantRead(role);
secret.GrantWrite(role);
If, as in the following example, your secret was created with a KMS key:
Role role;
var key = new Key(this, "KMS");
var secret = new Secret(this, "Secret", new SecretProps { 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.
The principal is automatically added to Secret resource policy and KMS Key policy for cross account access:
var otherAccount = new AccountPrincipal("1234");
var key = new Key(this, "KMS");
var secret = new Secret(this, "Secret", new SecretProps { EncryptionKey = key });
secret.GrantRead(otherAccount);
Rotating a Secret
Using a Custom Lambda Function
A rotation schedule can be added to a Secret using a custom Lambda function:
using Amazon.CDK.AWS.Lambda;
Function fn;
var secret = new Secret(this, "Secret");
secret.AddRotationSchedule("RotationSchedule", new RotationScheduleOptions {
RotationLambda = fn,
AutomaticallyAfter = Duration.Days(15)
});
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:
var secret = new Secret(this, "Secret");
secret.AddRotationSchedule("RotationSchedule", new RotationScheduleOptions {
HostedRotation = HostedRotation.MysqlSingleUser()
});
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
:
Vpc myVpc;
Connections dbConnections;
Secret secret;
var myHostedRotation = HostedRotation.MysqlSingleUser(new SingleUserHostedRotationOptions { Vpc = myVpc });
secret.AddRotationSchedule("RotationSchedule", new RotationScheduleOptions { HostedRotation = myHostedRotation });
dbConnections.AllowDefaultPortFrom(myHostedRotation);
See also Automating secret creation in AWS CloudFormation.
Rotating database credentials
Define a SecretRotation
to rotate database credentials:
Secret mySecret;
IConnectable myDatabase;
Vpc myVpc;
new SecretRotation(this, "SecretRotation", new SecretRotationProps {
Application = SecretRotationApplication.MYSQL_ROTATION_SINGLE_USER, // MySQL single user scheme
Secret = mySecret,
Target = myDatabase, // a Connectable
Vpc = myVpc, // The VPC where the secret rotation application will be deployed
ExcludeCharacters = " %+:;{}"
});
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:
Secret myUserSecret;
Secret myMasterSecret;
IConnectable myDatabase;
Vpc myVpc;
new SecretRotation(this, "SecretRotation", new SecretRotationProps {
Application = SecretRotationApplication.MYSQL_ROTATION_MULTI_USER,
Secret = myUserSecret, // The secret that will be rotated
MasterSecret = myMasterSecret, // The secret used for the rotation
Target = myDatabase,
Vpc = myVpc
});
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 suffx); 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.
var secretCompleteArn = "arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret-f3gDy9";
var secretPartialArn = "arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret"; // No Secrets Manager suffix
var encryptionKey = Key.FromKeyArn(this, "MyEncKey", "arn:aws:kms:eu-west-1:111111111111:key/21c4b39b-fde2-4273-9ac0-d9bb5c0d0030");
var mySecretFromCompleteArn = Secret.FromSecretCompleteArn(this, "SecretFromCompleteArn", secretCompleteArn);
var mySecretFromPartialArn = Secret.FromSecretPartialArn(this, "SecretFromPartialArn", secretPartialArn);
var mySecretFromName = Secret.FromSecretNameV2(this, "SecretFromName", "MySecret");
var mySecretFromAttrs = Secret.FromSecretAttributes(this, "SecretFromAttributes", new SecretAttributes {
SecretCompleteArn = secretCompleteArn,
EncryptionKey = encryptionKey
});
Replicating secrets
Secrets can be replicated to multiple regions by specifying replicaRegions
:
Key myKey;
new Secret(this, "Secret", new SecretProps {
ReplicaRegions = new [] { new ReplicaRegion {
Region = "eu-west-1"
}, new ReplicaRegion {
Region = "eu-central-1",
EncryptionKey = myKey
} }
});
Alternatively, use addReplicaRegion()
:
var secret = new Secret(this, "Secret");
secret.AddReplicaRegion("eu-west-1");
Classes
AttachedSecretOptions | Options to add a secret attachment to a secret. |
AttachmentTargetType | The type of service or database that's being associated with the secret. |
CfnResourcePolicy | A CloudFormation |
CfnResourcePolicyProps | Properties for defining a |
CfnRotationSchedule | A CloudFormation |
CfnRotationSchedule.HostedRotationLambdaProperty | Creates a new Lambda rotation function based on one of the Secrets Manager rotation function templates . |
CfnRotationSchedule.RotationRulesProperty | The rotation schedule and window. |
CfnRotationScheduleProps | Properties for defining a |
CfnSecret | A CloudFormation |
CfnSecret.GenerateSecretStringProperty | Generates a random password. |
CfnSecret.ReplicaRegionProperty | Specifies a |
CfnSecretProps | Properties for defining a |
CfnSecretTargetAttachment | A CloudFormation |
CfnSecretTargetAttachmentProps | Properties for defining a |
HostedRotation | A hosted rotation. |
HostedRotationType | Hosted rotation type. |
MultiUserHostedRotationOptions | Multi user hosted rotation options. |
ReplicaRegion | Secret replica region. |
ResourcePolicy | Resource Policy for SecretsManager Secrets. |
ResourcePolicyProps | Construction properties for a ResourcePolicy. |
RotationSchedule | A rotation schedule. |
RotationScheduleOptions | Options to add a rotation schedule to a secret. |
RotationScheduleProps | Construction properties for a RotationSchedule. |
Secret | Creates a new secret in AWS SecretsManager. |
SecretAttachmentTargetProps | Attachment target specifications. |
SecretAttributes | Attributes required to import an existing secret into the Stack. |
SecretProps | The properties required to create a new secret in AWS Secrets Manager. |
SecretRotation | Secret rotation for a service or database. |
SecretRotationApplication | A secret rotation serverless application. |
SecretRotationApplicationOptions | Options for a SecretRotationApplication. |
SecretRotationProps | Construction properties for a SecretRotation. |
SecretStringGenerator | Configuration to generate secrets such as passwords automatically. |
SecretStringValueBeta1 | (deprecated) An experimental class used to specify an initial secret value for a Secret. |
SecretTargetAttachment | An attached secret. |
SecretTargetAttachmentProps | Construction properties for an AttachedSecret. |
SingleUserHostedRotationOptions | Single user hosted rotation options. |
Interfaces
CfnRotationSchedule.IHostedRotationLambdaProperty | Creates a new Lambda rotation function based on one of the Secrets Manager rotation function templates . |
CfnRotationSchedule.IRotationRulesProperty | The rotation schedule and window. |
CfnSecret.IGenerateSecretStringProperty | Generates a random password. |
CfnSecret.IReplicaRegionProperty | Specifies a |
IAttachedSecretOptions | Options to add a secret attachment to a secret. |
ICfnResourcePolicyProps | Properties for defining a |
ICfnRotationScheduleProps | Properties for defining a |
ICfnSecretProps | Properties for defining a |
ICfnSecretTargetAttachmentProps | Properties for defining a |
IMultiUserHostedRotationOptions | Multi user hosted rotation options. |
IReplicaRegion | Secret replica region. |
IResourcePolicyProps | Construction properties for a ResourcePolicy. |
IRotationScheduleOptions | Options to add a rotation schedule to a secret. |
IRotationScheduleProps | Construction properties for a RotationSchedule. |
ISecret | A secret in AWS Secrets Manager. |
ISecretAttachmentTarget | A secret attachment target. |
ISecretAttachmentTargetProps | Attachment target specifications. |
ISecretAttributes | Attributes required to import an existing secret into the Stack. |
ISecretProps | The properties required to create a new secret in AWS Secrets Manager. |
ISecretRotationApplicationOptions | Options for a SecretRotationApplication. |
ISecretRotationProps | Construction properties for a SecretRotation. |
ISecretStringGenerator | Configuration to generate secrets such as passwords automatically. |
ISecretTargetAttachment | |
ISecretTargetAttachmentProps | Construction properties for an AttachedSecret. |
ISingleUserHostedRotationOptions | Single user hosted rotation options. |