# AWS Secrets Manager Construct Library
<!--BEGIN STABILITY BANNER-->---
> 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](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).
---
<!--END STABILITY BANNER-->
```python
import aws_cdk.aws_secretsmanager as 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:
```python
# Default secret
secret = secretsmanager.Secret(self, "Secret")
# Using the default secret
iam.User(self, "User",
password=secret.secret_value
)
# Templated secret
templated_secret = secretsmanager.Secret(self, "TemplatedSecret",
generate_secret_string=secretsmanager.SecretStringGenerator(
secret_string_template=JSON.stringify({"username": "user"}),
generate_string_key="password"
)
)
# Using the templated secret
iam.User(self, "OtherUser",
user_name=templated_secret.secret_value_from_json("username").to_string(),
password=templated_secret.secret_value_from_json("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:
```python
# 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html).
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:
```python
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:
```python
# 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:
```python
other_account = iam.AccountPrincipal("1234")
key = kms.Key(self, "KMS")
secret = secretsmanager.Secret(self, "Secret", encryption_key=key)
secret.grant_read(other_account)
```
## Rotating a Secret
### Using a Custom Lambda Function
A rotation schedule can be added to a Secret using a custom Lambda function:
```python
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)
)
```
Note: The required permissions for Lambda to call SecretsManager and the other way round are automatically granted based on [AWS Documentation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets-required-permissions.html) as long as the Lambda is not imported.
See [Overview of the Lambda Rotation Function](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets-lambda-function-overview.html) 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:
```python
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`:
```python
# my_vpc: ec2.Vpc
# 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)
```
See also [Automating secret creation in AWS CloudFormation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/integrating_cloudformation.html).
## Rotating database credentials
Define a `SecretRotation` to rotate database credentials:
```python
# 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:
```json
{
"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:
```python
# 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
)
```
See also [aws-rds](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/aws-rds/README.md) 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.
```python
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`:
```python
# 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()`:
```python
secret = secretsmanager.Secret(self, "Secret")
secret.add_replica_region("eu-west-1")
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-secretsmanager",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/26/56/7a3b4ed9e3e58af15abb718d23842a31a2708333865c70754c9fa4f4aa7f/aws-cdk.aws-secretsmanager-1.204.0.tar.gz",
"platform": null,
"description": "# AWS Secrets Manager Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n> AWS CDK v1 has reached End-of-Support on 2023-06-01.\n> This package is no longer being updated, and users should migrate to AWS CDK v2.\n>\n> For more information on how to migrate, see the [*Migrating to AWS CDK v2* guide](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).\n\n---\n<!--END STABILITY BANNER-->\n\n```python\nimport aws_cdk.aws_secretsmanager as secretsmanager\n```\n\n## Create a new Secret in a Stack\n\nIn order to have SecretsManager generate a new secret value automatically,\nyou can get started with the following:\n\n```python\n# Default secret\nsecret = secretsmanager.Secret(self, \"Secret\")\n# Using the default secret\niam.User(self, \"User\",\n password=secret.secret_value\n)\n# Templated secret\ntemplated_secret = secretsmanager.Secret(self, \"TemplatedSecret\",\n generate_secret_string=secretsmanager.SecretStringGenerator(\n secret_string_template=JSON.stringify({\"username\": \"user\"}),\n generate_string_key=\"password\"\n )\n)\n# Using the templated secret\niam.User(self, \"OtherUser\",\n user_name=templated_secret.secret_value_from_json(\"username\").to_string(),\n password=templated_secret.secret_value_from_json(\"password\")\n)\n```\n\nIf you need to use a pre-existing secret, the recommended way is to manually\nprovision the secret in *AWS SecretsManager* and use the `Secret.fromSecretArn`\nor `Secret.fromSecretAttributes` method to make it available in your CDK Application:\n\n```python\n# encryption_key: kms.Key\n\nsecret = secretsmanager.Secret.from_secret_attributes(self, \"ImportedSecret\",\n secret_arn=\"arn:aws:secretsmanager:<region>:<account-id-number>:secret:<secret-name>-<random-6-characters>\",\n # If the secret is encrypted using a KMS-hosted CMK, either import or reference that key:\n encryption_key=encryption_key\n)\n```\n\nSecretsManager secret values can only be used in select set of properties. For the\nlist of properties, see [the CloudFormation Dynamic References documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html).\n\nA secret can set `RemovalPolicy`. If it set to `RETAIN`, that removing a secret will fail.\n\n## Grant permission to use the secret to a role\n\nYou must grant permission to a resource for that resource to be allowed to\nuse a secret. This can be achieved with the `Secret.grantRead` and/or `Secret.grantWrite`\nmethod, depending on your need:\n\n```python\nrole = iam.Role(self, \"SomeRole\", assumed_by=iam.AccountRootPrincipal())\nsecret = secretsmanager.Secret(self, \"Secret\")\nsecret.grant_read(role)\nsecret.grant_write(role)\n```\n\nIf, as in the following example, your secret was created with a KMS key:\n\n```python\n# role: iam.Role\n\nkey = kms.Key(self, \"KMS\")\nsecret = secretsmanager.Secret(self, \"Secret\", encryption_key=key)\nsecret.grant_read(role)\nsecret.grant_write(role)\n```\n\nthen `Secret.grantRead` and `Secret.grantWrite` will also grant the role the\nrelevant encrypt and decrypt permissions to the KMS key through the\nSecretsManager service principal.\n\nThe principal is automatically added to Secret resource policy and KMS Key policy for cross account access:\n\n```python\nother_account = iam.AccountPrincipal(\"1234\")\nkey = kms.Key(self, \"KMS\")\nsecret = secretsmanager.Secret(self, \"Secret\", encryption_key=key)\nsecret.grant_read(other_account)\n```\n\n## Rotating a Secret\n\n### Using a Custom Lambda Function\n\nA rotation schedule can be added to a Secret using a custom Lambda function:\n\n```python\nimport aws_cdk.aws_lambda as lambda_\n\n# fn: lambda.Function\n\nsecret = secretsmanager.Secret(self, \"Secret\")\n\nsecret.add_rotation_schedule(\"RotationSchedule\",\n rotation_lambda=fn,\n automatically_after=Duration.days(15)\n)\n```\n\nNote: The required permissions for Lambda to call SecretsManager and the other way round are automatically granted based on [AWS Documentation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets-required-permissions.html) as long as the Lambda is not imported.\n\nSee [Overview of the Lambda Rotation Function](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets-lambda-function-overview.html) on how to implement a Lambda Rotation Function.\n\n### Using a Hosted Lambda Function\n\nUse the `hostedRotation` prop to rotate a secret with a hosted Lambda function:\n\n```python\nsecret = secretsmanager.Secret(self, \"Secret\")\n\nsecret.add_rotation_schedule(\"RotationSchedule\",\n hosted_rotation=secretsmanager.HostedRotation.mysql_single_user()\n)\n```\n\nHosted rotation is available for secrets representing credentials for MySQL, PostgreSQL, Oracle,\nMariaDB, SQLServer, Redshift and MongoDB (both for the single and multi user schemes).\n\nWhen deployed in a VPC, the hosted rotation implements `ec2.IConnectable`:\n\n```python\n# my_vpc: ec2.Vpc\n# db_connections: ec2.Connections\n# secret: secretsmanager.Secret\n\n\nmy_hosted_rotation = secretsmanager.HostedRotation.mysql_single_user(vpc=my_vpc)\nsecret.add_rotation_schedule(\"RotationSchedule\", hosted_rotation=my_hosted_rotation)\ndb_connections.allow_default_port_from(my_hosted_rotation)\n```\n\nSee also [Automating secret creation in AWS CloudFormation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/integrating_cloudformation.html).\n\n## Rotating database credentials\n\nDefine a `SecretRotation` to rotate database credentials:\n\n```python\n# my_secret: secretsmanager.Secret\n# my_database: ec2.IConnectable\n# my_vpc: ec2.Vpc\n\n\nsecretsmanager.SecretRotation(self, \"SecretRotation\",\n application=secretsmanager.SecretRotationApplication.MYSQL_ROTATION_SINGLE_USER, # MySQL single user scheme\n secret=my_secret,\n target=my_database, # a Connectable\n vpc=my_vpc, # The VPC where the secret rotation application will be deployed\n exclude_characters=\" %+:;{}\"\n)\n```\n\nThe secret must be a JSON string with the following format:\n\n```json\n{\n \"engine\": \"<required: database engine>\",\n \"host\": \"<required: instance host name>\",\n \"username\": \"<required: username>\",\n \"password\": \"<required: password>\",\n \"dbname\": \"<optional: database name>\",\n \"port\": \"<optional: if not specified, default port will be used>\",\n \"masterarn\": \"<required for multi user rotation: the arn of the master secret which will be used to create users/change passwords>\"\n}\n```\n\nFor the multi user scheme, a `masterSecret` must be specified:\n\n```python\n# my_user_secret: secretsmanager.Secret\n# my_master_secret: secretsmanager.Secret\n# my_database: ec2.IConnectable\n# my_vpc: ec2.Vpc\n\n\nsecretsmanager.SecretRotation(self, \"SecretRotation\",\n application=secretsmanager.SecretRotationApplication.MYSQL_ROTATION_MULTI_USER,\n secret=my_user_secret, # The secret that will be rotated\n master_secret=my_master_secret, # The secret used for the rotation\n target=my_database,\n vpc=my_vpc\n)\n```\n\nSee also [aws-rds](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/aws-rds/README.md) where\ncredentials generation and rotation is integrated.\n\n## Importing Secrets\n\nExisting secrets can be imported by ARN, name, and other attributes (including the KMS key used to encrypt the secret).\nSecrets imported by name should use the short-form of the name (without the SecretsManager-provided suffx);\nthe secret name must exist in the same account and region as the stack.\nImporting by name makes it easier to reference secrets created in different regions, each with their own suffix and ARN.\n\n```python\nsecret_complete_arn = \"arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret-f3gDy9\"\nsecret_partial_arn = \"arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret\" # No Secrets Manager suffix\nencryption_key = kms.Key.from_key_arn(self, \"MyEncKey\", \"arn:aws:kms:eu-west-1:111111111111:key/21c4b39b-fde2-4273-9ac0-d9bb5c0d0030\")\nmy_secret_from_complete_arn = secretsmanager.Secret.from_secret_complete_arn(self, \"SecretFromCompleteArn\", secret_complete_arn)\nmy_secret_from_partial_arn = secretsmanager.Secret.from_secret_partial_arn(self, \"SecretFromPartialArn\", secret_partial_arn)\nmy_secret_from_name = secretsmanager.Secret.from_secret_name_v2(self, \"SecretFromName\", \"MySecret\")\nmy_secret_from_attrs = secretsmanager.Secret.from_secret_attributes(self, \"SecretFromAttributes\",\n secret_complete_arn=secret_complete_arn,\n encryption_key=encryption_key\n)\n```\n\n## Replicating secrets\n\nSecrets can be replicated to multiple regions by specifying `replicaRegions`:\n\n```python\n# my_key: kms.Key\n\nsecretsmanager.Secret(self, \"Secret\",\n replica_regions=[secretsmanager.ReplicaRegion(\n region=\"eu-west-1\"\n ), secretsmanager.ReplicaRegion(\n region=\"eu-central-1\",\n encryption_key=my_key\n )\n ]\n)\n```\n\nAlternatively, use `addReplicaRegion()`:\n\n```python\nsecret = secretsmanager.Secret(self, \"Secret\")\nsecret.add_replica_region(\"eu-west-1\")\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::SecretsManager",
"version": "1.204.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a482d1138a9822848b22e20e5de6d8c00ec5f500438eb1549f0c44f5e95c5a8f",
"md5": "9872420ac8249210d6efe220e296fda3",
"sha256": "21f5ded32cf5d38616addd9d8709560bdbae7542af8ada58b7e1c9cf26890b4d"
},
"downloads": -1,
"filename": "aws_cdk.aws_secretsmanager-1.204.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9872420ac8249210d6efe220e296fda3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 224041,
"upload_time": "2023-06-19T21:01:14",
"upload_time_iso_8601": "2023-06-19T21:01:14.057837Z",
"url": "https://files.pythonhosted.org/packages/a4/82/d1138a9822848b22e20e5de6d8c00ec5f500438eb1549f0c44f5e95c5a8f/aws_cdk.aws_secretsmanager-1.204.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "26567a3b4ed9e3e58af15abb718d23842a31a2708333865c70754c9fa4f4aa7f",
"md5": "65b75c6e09f27b819c3b318f31655b7a",
"sha256": "691cf1fe602fc7dcc8d6d6e472e7e3df44992f1921a1f620dbf6f72fb86d9356"
},
"downloads": -1,
"filename": "aws-cdk.aws-secretsmanager-1.204.0.tar.gz",
"has_sig": false,
"md5_digest": "65b75c6e09f27b819c3b318f31655b7a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 224018,
"upload_time": "2023-06-19T21:07:20",
"upload_time_iso_8601": "2023-06-19T21:07:20.836313Z",
"url": "https://files.pythonhosted.org/packages/26/56/7a3b4ed9e3e58af15abb718d23842a31a2708333865c70754c9fa4f4aa7f/aws-cdk.aws-secretsmanager-1.204.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-19 21:07:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-secretsmanager"
}
JSON
