Metadata-Version: 2.1
Name: aws-cdk.aws-secretsmanager
Version: 1.43.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 without compilation. 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 without compilation. 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).
        
        ### 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
        # 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
        SecretRotation(self, "SecretRotation",
            application=SecretRotationApplication.MYSQL_ROTATION_SINGLE_USER, # MySQL single user scheme
            secret=my_secret,
            target=my_database, # a Connectable
            vpc=my_vpc
        )
        ```
        
        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
        SecretRotation(stack, "SecretRotation",
            application=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.
        
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
