# @aws-cdk/aws-secretsmanager > The CDK Construct Library for AWS::SecretsManager Latest version **1.204.0** (published 2023-06-19) · Apache-2.0 license · 0 weekly downloads > **Deprecated.** This package is deprecated. ## Install ```sh npm install @aws-cdk/aws-secretsmanager pnpm add @aws-cdk/aws-secretsmanager yarn add @aws-cdk/aws-secretsmanager bun add @aws-cdk/aws-secretsmanager ``` ## Health **Score 10/100 (F)** — status: deprecated. Negative: deprecated. ## Facts | | | |---|---| | Version | 1.204.0 | | Published | 2023-06-19 | | First published | 2018-11-19 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | CommonJS | | Node | >= 14.15.0 | | Dependencies | 8 | | Unpacked size | 1 MB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 12898 | | Author | Amazon Web Services | | Maintainers | romainmuller, amzn-oss, rix0rrr, aws-cdk-team | | Keywords | aws, cdk, constructs, aws-secretsmanager | ## Links - npm: https://www.npmjs.com/package/@aws-cdk/aws-secretsmanager - Repository: https://github.com/aws/aws-cdk - Issues: https://github.com/aws/aws-cdk/issues - npm.io page: https://npm.io/package/@aws-cdk/aws-secretsmanager ## Dependencies (8) - [constructs](https://npm.io/package/constructs.md) ^3.3.69 - [@aws-cdk/core](https://npm.io/package/@aws-cdk/core.md) 1.204.0 - [@aws-cdk/cx-api](https://npm.io/package/@aws-cdk/cx-api.md) 1.204.0 - [@aws-cdk/aws-ec2](https://npm.io/package/@aws-cdk/aws-ec2.md) 1.204.0 - [@aws-cdk/aws-iam](https://npm.io/package/@aws-cdk/aws-iam.md) 1.204.0 - [@aws-cdk/aws-kms](https://npm.io/package/@aws-cdk/aws-kms.md) 1.204.0 - [@aws-cdk/aws-sam](https://npm.io/package/@aws-cdk/aws-sam.md) 1.204.0 - [@aws-cdk/aws-lambda](https://npm.io/package/@aws-cdk/aws-lambda.md) 1.204.0 ## Alternatives - [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads - [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads - [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads - [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads - [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads ## Recent versions - 1.204.0 (latest) — 2023-06-19 - 1.203.0 — 2023-05-31 - 1.202.0 — 2023-05-22 - 1.201.0 — 2023-05-10 - 1.200.0 — 2023-04-26 - 1.199.0 — 2023-04-20 - 1.198.1 — 2023-03-31 - 1.198.0 — 2023-03-22 - 1.197.0 — 2023-03-14 - 1.196.0 — 2023-03-08 - 1.195.0 — 2023-03-02 - 1.194.0 — 2023-02-21 - 1.193.0 — 2023-02-15 - 1.192.0 — 2023-02-09 - 1.191.0 — 2023-01-31 - … 257 more at https://npm.io/package/@aws-cdk/aws-secretsmanager/versions ## README # AWS Secrets Manager Construct Library --- ![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge) > 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][doc]. > > [doc]: https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html --- ```ts nofixture 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: ```ts // Default secret const secret = new secretsmanager.Secret(this, 'Secret'); // Using the default secret new iam.User(this, 'User', { password: secret.secretValue, }); // Templated secret const templatedSecret = new secretsmanager.Secret(this, 'TemplatedSecret', { generateSecretString: { secretStringTemplate: JSON.stringify({ username: 'user' }), generateStringKey: 'password', }, }); // Using the templated secret new iam.User(this, 'OtherUser', { 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: ```ts declare const encryptionKey: kms.Key; const secret = secretsmanager.Secret.fromSecretAttributes(this, 'ImportedSecret', { secretArn: 'arn:aws:secretsmanager:::secret:-', // If the secret is encrypted using a KMS-hosted CMK, either import or reference that key: encryptionKey, }); ``` 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: ```ts const role = new iam.Role(this, 'SomeRole', { assumedBy: new iam.AccountRootPrincipal() }); const secret = new secretsmanager.Secret(this, 'Secret'); secret.grantRead(role); secret.grantWrite(role); ``` If, as in the following example, your secret was created with a KMS key: ```ts declare const role: iam.Role; const key = new kms.Key(this, 'KMS'); const secret = new secretsmanager.Secret(this, '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. The principal is automatically added to Secret resource policy and KMS Key policy for cross account access: ```ts const otherAccount = new iam.AccountPrincipal('1234'); const key = new kms.Key(this, 'KMS'); const secret = new secretsmanager.Secret(this, 'Secret', { 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: ```ts import * as lambda from '@aws-cdk/aws-lambda'; declare const fn: lambda.Function; const secret = new secretsmanager.Secret(this, 'Secret'); secret.addRotationSchedule('RotationSchedule', { 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](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: ```ts const secret = new secretsmanager.Secret(this, 'Secret'); secret.addRotationSchedule('RotationSchedule', { hostedRotation: secretsmanager.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`: ```ts declare const myVpc: ec2.Vpc; declare const dbConnections: ec2.Connections; declare const secret: secretsmanager.Secret; const myHostedRotation = secretsmanager.HostedRotation.mysqlSingleUser({ vpc: myVpc }); secret.addRotationSchedule('RotationSchedule', { hostedRotation: myHostedRotation }); dbConnections.allowDefaultPortFrom(myHostedRotation); ``` 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: ```ts declare const mySecret: secretsmanager.Secret; declare const myDatabase: ec2.IConnectable; declare const myVpc: ec2.Vpc; new secretsmanager.SecretRotation(this, 'SecretRotation', { application: secretsmanager.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: ' %+:;{}', // characters to never use when generating new passwords; // by default, no characters are excluded, // which might cause problems with some services, like DMS }); ``` The secret must be a JSON string with the following format: ```json { "engine": "", "host": "", "username": "", "password": "", "dbname": "", "port": "", "masterarn": "" } ``` For the multi user scheme, a `masterSecret` must be specified: ```ts declare const myUserSecret: secretsmanager.Secret; declare const myMasterSecret: secretsmanager.Secret; declare const myDatabase: ec2.IConnectable; declare const myVpc: ec2.Vpc; new secretsmanager.SecretRotation(this, 'SecretRotation', { application: secretsmanager.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](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. ```ts const secretCompleteArn = 'arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret-f3gDy9'; const secretPartialArn = 'arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret'; // No Secrets Manager suffix const encryptionKey = kms.Key.fromKeyArn(this, 'MyEncKey', 'arn:aws:kms:eu-west-1:111111111111:key/21c4b39b-fde2-4273-9ac0-d9bb5c0d0030'); const mySecretFromCompleteArn = secretsmanager.Secret.fromSecretCompleteArn(this, 'SecretFromCompleteArn', secretCompleteArn); const mySecretFromPartialArn = secretsmanager.Secret.fromSecretPartialArn(this, 'SecretFromPartialArn', secretPartialArn); const mySecretFromName = secretsmanager.Secret.fromSecretNameV2(this, 'SecretFromName', 'MySecret') const mySecretFromAttrs = secretsmanager.Secret.fromSecretAttributes(this, 'SecretFromAttributes', { secretCompleteArn, encryptionKey, }); ``` ## Replicating secrets Secrets can be replicated to multiple regions by specifying `replicaRegions`: ```ts declare const myKey: kms.Key; new secretsmanager.Secret(this, 'Secret', { replicaRegions: [ { region: 'eu-west-1', }, { region: 'eu-central-1', encryptionKey: myKey, } ] }); ``` Alternatively, use `addReplicaRegion()`: ```ts const secret = new secretsmanager.Secret(this, 'Secret'); secret.addReplicaRegion('eu-west-1'); ``` --- _Source: https://npm.io/package/@aws-cdk/aws-secretsmanager · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._