Metadata-Version: 2.1
Name: aws-cdk.aws-secretsmanager
Version: 1.64.0
Summary: The CDK Construct Library for AWS::SecretsManager
Home-page: https://github.com/aws/aws-cdk
Author: Amazon Web Services
License: Apache-2.0
Project-URL: Source, https://github.com/aws/aws-cdk.git
Description: ## AWS Secrets Manager Construct Library
        
        <!--BEGIN STABILITY BANNER-->---
        
        
        ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
        
        ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
        
        ---
        <!--END STABILITY BANNER-->
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        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
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        # Default secret
        secret = secretsmanager.Secret(self, "Secret")
        secret.grant_read(role)
        
        iam.User(self, "User",
            password=secret.secret_value
        )
        
        # Templated secret
        templated_secret = secretsmanager.Secret(self, "TemplatedSecret",
            generate_secret_string=SecretStringGenerator(
                secret_string_template=JSON.stringify(username="user"),
                generate_string_key="password"
            )
        )
        
        iam.User(self, "OtherUser",
            user_name=templated_secret.secret_value_from_json("username").to_string(),
            password=templated_secret.secret_value_from_json("password")
        )
        ```
        
        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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        secret = secretsmanager.Secret.from_secret_attributes(scope, "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.grantUpdate`
        method, depending on your need:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        role = iam.Role(stack, "SomeRole", assumed_by=iam.AccountRootPrincipal())
        secret = secretsmanager.Secret(stack, "Secret")
        secret.grant_read(role)
        secret.grant_write(role)
        ```
        
        If, as in the following example, your secret was created with a KMS key:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        key = kms.Key(stack, "KMS")
        secret = secretsmanager.Secret(stack, "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.
        
        ### Rotating a Secret with a custom Lambda function
        
        A rotation schedule can be added to a Secret using a custom Lambda function:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        fn = lambda_.Function(...)
        secret = secretsmanager.Secret(self, "Secret")
        
        secret.add_rotation_schedule("RotationSchedule",
            rotation_lambda=fn,
            automatically_after=Duration.days(15)
        )
        ```
        
        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.
        
        ### Rotating database credentials
        
        Define a `SecretRotation` to rotate database credentials:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        secretsmanager.SecretRotation(stack, "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 can used 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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        import aws_cdk.aws_kms as kms
        
        secret_arn = "arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret-f3gDy9"
        encryption_key = kms.Key.from_key_arn(stack, "MyEncKey", "arn:aws:kms:eu-west-1:111111111111:key/21c4b39b-fde2-4273-9ac0-d9bb5c0d0030")
        my_secret_from_arn = secretsmanager.Secret.from_secret_arn(stack, "SecretFromArn", secret_arn)
        my_secret_from_name = secretsmanager.Secret.from_secret_name(stack, "SecretFromName", "MySecret")# Note: the -f3gDy9 suffix is optional
        my_secret_from_attrs = secretsmanager.Secret.from_secret_attributes(stack, "SecretFromAttributes",
            secret_arn=secret_arn,
            encryption_key=encryption_key,
            secret_name="MySecret"
        )
        ```
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Typing :: Typed
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved
Requires-Python: >=3.6
Description-Content-Type: text/markdown
