Resource Policy for SecretsManager Secrets.

Policies define the operations that are allowed on this resource.

You almost never need to define this construct directly.

All AWS resources that support resource policies have a method called
`addToResourcePolicy()`, which will automatically create a new resource
policy if one doesn't exist yet, otherwise it will add to the existing
policy.

Prefer to use `addToResourcePolicy()` instead.

ResourcePolicy

The secret to attach a resource-based permissions policy.

secret

RotationSchedule

The secret to rotate.

If hosted rotation is used, this 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>
}
```

This is typically the case for a secret referenced from an `AWS::SecretsManager::SecretTargetAttachment`
or an `ISecret` returned by the `attach()` method of `Secret`.

Specifies the number of days after the previous rotation before Secrets Manager triggers the next automatic rotation.

The minimum value is 4 hours.
The maximum value is 1000 days.

A value of zero (`Duration.days(0)`) will not create RotationRules.

automaticallyAfter

hostedRotation

Specifies whether to rotate the secret immediately or wait until the next scheduled rotation window.

rotateImmediatelyOnUpdate

A Lambda function that can rotate the secret.

rotationLambda

Creates a new secret in AWS SecretsManager.

addReplicaRegion

addRotationSchedule

Adds a statement to the IAM resource policy associated with this secret.

If this secret was created in this stack, a resource policy will be
automatically created upon the first call to `addToResourcePolicy`. If
the secret is imported, then this is a no-op.

addToResourcePolicy

attach

Returns a key which can be used within an AWS CloudFormation dynamic reference to dynamically load this secret from AWS Secrets Manager.

cfnDynamicReferenceKey

Denies the `DeleteSecret` action to all principals within the current account.

denyAccountRootDelete

grantRead

grantWrite

Interpret the secret as a JSON object and return a field's value from it as a `SecretValue`.

secretValueFromJson

Secret

An optional, human-friendly description of the secret.

description

The customer-managed encryption key to use for encrypting the secret value.

encryptionKey

Configuration for how to generate a secret value.

Only one of `secretString` and `generateSecretString` can be provided.

generateSecretString

Policy to apply when the secret is removed from this stack.

removalPolicy

A list of regions where to replicate this secret.

replicaRegions

A name for the secret.

Note that deleting secrets from SecretsManager does not happen immediately, but after a 7 to
30 days blackout period. During that period, it is not possible to create another secret that shares the same name.

secretName

Initial value for a JSON secret.

**NOTE:** *It is **highly** encouraged to leave this field undefined and allow SecretsManager to create the secret value.
The secret object -- if provided -- will be included in the output of the cdk as part of synthesis,
and will appear in the CloudFormation template in the console. This can be secure(-ish) if that value is merely reference to
another resource (or one of its attributes), but if the value is a plaintext string, it will be visible to anyone with access
to the CloudFormation template (via the AWS Console, SDKs, or CLI).

Specifies a JSON object that you want to encrypt and store in this new version of the secret.
To specify a simple string value instead, use `SecretProps.secretStringValue`

Only one of `secretStringBeta1`, `secretStringValue`, 'secretObjectValue', and `generateSecretString` can be provided.

secretObjectValue

Initial value for the secret.

**NOTE:** *It is **highly** encouraged to leave this field undefined and allow SecretsManager to create the secret value.
The secret string -- if provided -- will be included in the output of the cdk as part of synthesis,
and will appear in the CloudFormation template in the console. This can be secure(-ish) if that value is merely reference to
another resource (or one of its attributes), but if the value is a plaintext string, it will be visible to anyone with access
to the CloudFormation template (via the AWS Console, SDKs, or CLI).

Specifies text data that you want to encrypt and store in this new version of the secret.
May be a simple string value, or a string representation of a JSON structure.

Only one of `secretStringBeta1`, `secretStringValue`, and `generateSecretString` can be provided.

secretStringBeta1

Initial value for the secret.

**NOTE:** *It is **highly** encouraged to leave this field undefined and allow SecretsManager to create the secret value.
The secret string -- if provided -- will be included in the output of the cdk as part of synthesis,
and will appear in the CloudFormation template in the console. This can be secure(-ish) if that value is merely reference to
another resource (or one of its attributes), but if the value is a plaintext string, it will be visible to anyone with access
to the CloudFormation template (via the AWS Console, SDKs, or CLI).

Specifies text data that you want to encrypt and store in this new version of the secret.
May be a simple string value. To provide a string representation of JSON structure, use `SecretProps.secretObjectValue` instead.

Only one of `secretStringBeta1`, `secretStringValue`, 'secretObjectValue', and `generateSecretString` can be provided.

secretStringValue

Secret rotation for a service or database.

SecretRotation

The serverless application for the rotation.

application

The secret to rotate. It 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>
}
```

This is typically the case for a secret referenced from an `AWS::SecretsManager::SecretTargetAttachment`
or an `ISecret` returned by the `attach()` method of `Secret`.

target

The VPC where the Lambda rotation function will run.

Specifies the number of days after the previous rotation before Secrets Manager triggers the next automatic rotation.

The VPC interface endpoint to use for the Secrets Manager API.

If you enable private DNS hostnames for your VPC private endpoint (the default), you don't
need to specify an endpoint. The standard Secrets Manager DNS hostname the Secrets Manager
CLI and SDKs use by default (https://secretsmanager.<region>.amazonaws.com) automatically
resolves to your VPC endpoint.

endpoint

Characters which should not appear in the generated password.

excludeCharacters

The master secret for a multi user rotation scheme.

masterSecret

The security group for the Lambda rotation function.

securityGroup

The type of subnets in the VPC where the Lambda rotation function will run.

vpcSubnets

Forward any additions to the resource policy to the original secret.

This is required because a secret can only have a single resource policy.
If we do not forward policy additions, a new policy resource is created using the secret attachment ARN.
This ends up being rejected by CloudFormation.

SecretTargetAttachment

Attaches a resource-based permission policy to a secret.

A resource-based policy is optional. If a secret already has a resource policy attached, you must first remove it before attaching a new policy using this CloudFormation resource. You can remove the policy using the [console](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html) , [CLI](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/delete-resource-policy.html) , or [API](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_DeleteResourcePolicy.html) . For more information, see [Authentication and access control for Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html) .

*Required permissions:* `secretsmanager:PutResourcePolicy` , `secretsmanager:GetResourcePolicy` . For more information, see [IAM policy actions for Secrets Manager](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions) and [Authentication and access control in Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html) .

CfnResourcePolicy

A JSON-formatted string for an AWS resource-based policy.

For example policies, see [Permissions policy examples](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_examples.html) .

resourcePolicy

The ARN or name of the secret to attach the resource-based policy.

For an ARN, we recommend that you specify a complete ARN rather than a partial ARN.

secretId

Specifies whether to block resource-based policies that allow broad access to the secret.

By default, Secrets Manager blocks policies that allow broad access, for example those that use a wildcard for the principal.

blockPublicPolicy

Configure the rotation schedule and Lambda rotation function for a secret. For more information, see [How rotation works](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotate-secrets_how.html) .

For database credentials, refer to the following resources:

- Amazon RDS master user credentials: [AWS::RDS::DBCluster MasterUserSecret](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-rds-dbcluster-masterusersecret.html)
- Amazon Redshift admin user credentials: [AWS::Redshift::Cluster](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-redshift-cluster.html)

Choose one of the following options for the rotation function:

- Create a new rotation function using `HostedRotationLambda` based on a [Secrets Manager rotation function template](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_available-rotation-templates.html) .
- Use an existing rotation function by specifying its ARN with `RotationLambdaARN` .

> For database secrets defined in the same CloudFormation template as the database or service:
>
> - Use the [AWS::SecretsManager::SecretTargetAttachment](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-secretsmanager-secrettargetattachment.html) resource to populate the secret with connection details.
> - Add a `DependsOn` attribute to the `RotationSchedule` resource that uses a `SecretTargetAttachment` . This ensures the rotation is configured after the secret is populated with connection details. > You can define only one rotation schedule per secret.

CfnRotationSchedule

The ARN or name of the secret to rotate. This is unique for each rotation schedule definition.

To reference a secret also created in this template, use the [Ref](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) function with the secret's logical ID.

The list of metadata needed to successfully rotate a managed external secret.

externalSecretRotationMetadata

The ARN of the IAM role that is used by Secrets Manager to rotate a managed external secret.

externalSecretRotationRoleArn

Creates a new Lambda rotation function based on one of the [Secrets Manager rotation function templates](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_available-rotation-templates.html) . To use a rotation function that already exists, specify `RotationLambdaARN` instead.

You must specify `Transform: AWS::SecretsManager-2024-09-16` at the beginning of the CloudFormation template. Transforms are macros hosted by AWS CloudFormation that help you create and manage complex infrastructure. The `Transform: AWS::SecretsManager-2024-09-16` transform automatically extends the CloudFormation stack to include a nested stack (of type `AWS::CloudFormation::Stack` ), which then creates and updates on your behalf during subsequent stack operations, the appropriate rotation Lambda function for your database or service. For general information on transforms, see the [AWS CloudFormation documentation.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-reference.html)

For Amazon RDS master user credentials, see [AWS::RDS::DBCluster MasterUserSecret](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-rds-dbcluster-masterusersecret.html) .

For Amazon Redshift admin user credentials, see [AWS::Redshift::Cluster](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-redshift-cluster.html) .

hostedRotationLambda

Determines whether to rotate the secret immediately or wait until the next scheduled rotation window when the rotation schedule is updated.

The rotation schedule is defined in `RotationRules` .

The default for `RotateImmediatelyOnUpdate` is `true` . If you don't specify this value, Secrets Manager rotates the secret immediately.

If you set `RotateImmediatelyOnUpdate` to `false` , Secrets Manager tests the rotation configuration by running the [`testSecret` step](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotate-secrets_how.html) of the Lambda rotation function. This test creates an `AWSPENDING` version of the secret and then removes it.

> When changing an existing rotation schedule and setting `RotateImmediatelyOnUpdate` to `false` :
>
> - If using `AutomaticallyAfterDays` or a `ScheduleExpression` with `rate()` , the previously scheduled rotation might still occur.
> - To prevent unintended rotations, use a `ScheduleExpression` with `cron()` for granular control over rotation windows.

Rotation is an asynchronous process. For more information, see [How rotation works](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotate-secrets_how.html) .

The ARN of an existing Lambda rotation function.

To specify a rotation function that is also defined in this template, use the [Ref](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) function.

For Amazon RDS master user credentials, see [AWS::RDS::DBCluster MasterUserSecret](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-rds-dbcluster-masterusersecret.html) .

For Amazon Redshift admin user credentials, see [AWS::Redshift::Cluster](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-redshift-cluster.html) .

To create a new rotation function based on one of the [Secrets Manager rotation function templates](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_available-rotation-templates.html) , specify `HostedRotationLambda` instead.

rotationLambdaArn

A structure that defines the rotation configuration for this secret.

rotationRules

Creates a new secret.

A *secret* can be a password, a set of credentials such as a user name and password, an OAuth token, or other secret information that you store in an encrypted form in Secrets Manager.

For Amazon RDS master user credentials, see [AWS::RDS::DBCluster MasterUserSecret](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-rds-dbcluster-masterusersecret.html) .

For Amazon Redshift admin user credentials, see [AWS::Redshift::Cluster](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-redshift-cluster.html) .

To retrieve a secret in a CloudFormation template, use a *dynamic reference* . For more information, see [Retrieve a secret in an CloudFormation resource](https://docs.aws.amazon.com/secretsmanager/latest/userguide/cfn-example_reference-secret.html) .

For information about creating a secret in the console, see [Create a secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) . For information about creating a secret using the CLI or SDK, see [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) .

For information about retrieving a secret in code, see [Retrieve secrets from Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html) .

CfnSecret

A structure that specifies how to generate a password to encrypt and store in the secret.

To include a specific string in the secret, use `SecretString` instead. If you omit both `GenerateSecretString` and `SecretString` , you create an empty secret. When you make a change to this property, a new secret version is created.

We recommend that you specify the maximum length and include every character type that the system you are generating a password for can support.

The ARN, key ID, or alias of the AWS  key that Secrets Manager uses to encrypt the secret value in the secret.

An alias is always prefixed by `alias/` , for example `alias/aws/secretsmanager` . For more information, see [About aliases](https://docs.aws.amazon.com/kms/latest/developerguide/alias-about.html) .

To use a AWS  key in a different account, use the key ARN or the alias ARN.

If you don't specify this value, then Secrets Manager uses the key `aws/secretsmanager` . If that key doesn't yet exist, then Secrets Manager creates it for you automatically the first time it encrypts the secret value.

If the secret is in a different AWS account from the credentials calling the API, then you can't use `aws/secretsmanager` to encrypt the secret, and you must create and use a customer managed AWS  key.

kmsKeyId

The name of the new secret.

The secret name can contain ASCII letters, numbers, and the following characters: /_+=.@-

Do not end your secret name with a hyphen followed by six characters. If you do so, you risk confusion and unexpected results when searching for a secret by partial ARN. Secrets Manager automatically adds a hyphen and six random characters after the secret name at the end of the ARN.

name

A custom type that specifies a `Region` and the `KmsKeyId` for a replica secret.

The text to encrypt and store in the secret.

We recommend you use a JSON structure of key/value pairs for your secret value. To generate a random password, use `GenerateSecretString` instead. If you omit both `GenerateSecretString` and `SecretString` , you create an empty secret. When you make a change to this property, a new secret version is created.

secretString

A list of tags to attach to the secret.

Each tag is a key and value pair of strings in a JSON text string, for example:

`[{"Key":"CostCenter","Value":"12345"},{"Key":"environment","Value":"production"}]`

Secrets Manager tag key names are case sensitive. A tag with the key "ABC" is a different tag from one with key "abc".

Stack-level tags, tags you apply to the CloudFormation stack, are also attached to the secret.

If you check tags in permissions policies as part of your security strategy, then adding or removing a tag can change permissions. If the completion of this operation would result in you losing your permissions for this secret, then Secrets Manager blocks the operation and returns an `Access Denied` error. For more information, see [Control access to secrets using tags](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_examples.html#tag-secrets-abac) and [Limit access to identities with tags that match secrets' tags](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_examples.html#auth-and-access_tags2) .

For information about how to format a JSON parameter for the various command line tool environments, see [Using JSON for Parameters](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-json) . If your command-line tool or SDK requires quotation marks around the parameter, you should use single quotes to avoid confusion with the double quotes required in the JSON text.

The following restrictions apply to tags:

- Maximum number of tags per secret: 50
- Maximum key length: 127 Unicode characters in UTF-8
- Maximum value length: 255 Unicode characters in UTF-8
- Tag keys and values are case sensitive.
- Do not use the `aws:` prefix in your tag names or values because AWS reserves it for AWS use. You can't edit or delete tag names or values with this prefix. Tags with this prefix do not count against your tags per secret limit.
- If you use your tagging schema across multiple services and resources, other services might have restrictions on allowed characters. Generally allowed characters: letters, spaces, and numbers representable in UTF-8, plus the following special characters: + - = . _ : /

type

The `AWS::SecretsManager::SecretTargetAttachment` resource completes the final link between a Secrets Manager secret and the associated database by adding the database connection information to the secret JSON.

If you want to turn on automatic rotation for a database credential secret, the secret must contain the database connection information. For more information, see [JSON structure of Secrets Manager database credential secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_secret_json_structure.html) .

A single secret resource can only have one target attached to it.

When you remove a `SecretTargetAttachment` from a stack, Secrets Manager removes the database connection information from the secret with a `PutSecretValue` call.

For Amazon RDS master user credentials, see [AWS::RDS::DBCluster MasterUserSecret](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-rds-dbcluster-masterusersecret.html) .

For Amazon Redshift admin user credentials, see [AWS::Redshift::Cluster](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-redshift-cluster.html) .

CfnSecretTargetAttachment

The ARN or name of the secret.

To reference a secret also created in this template, use the see [Ref](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) function with the secret's logical ID. This field is unique for each target attachment definition.

targetId

A string that defines the type of service or database associated with the secret.

This value instructs Secrets Manager how to update the secret with the details of the service or database. This value must be one of the following:

- AWS::RDS::DBInstance
- AWS::RDS::DBCluster
- AWS::Redshift::Cluster
- AWS::RedshiftServerless::Namespace
- AWS::DocDB::DBInstance
- AWS::DocDB::DBCluster
- AWS::DocDBElastic::Cluster

AWS Secrets Manager

L2 Constructs5

ResourcePolicy

RotationSchedule

Secret

SecretRotation

SecretTargetAttachment

L1 Constructs4

CfnResourcePolicy

CfnRotationSchedule

CfnSecret

CfnSecretTargetAttachment

Learn AWS the Practical Way

Quick Facts

Related Links

More AWS Secrets Manager deep dives