SecretValue
- class aws_cdk.core.SecretValue(protected_value, *, stack_trace=None)
Bases:
Intrinsic
Work with secret values in the CDK.
Constructs that need secrets will declare parameters of type
SecretValue
.The actual values of these secrets should not be committed to your repository, or even end up in the synthesized CloudFormation template. Instead, you should store them in an external system like AWS Secrets Manager or SSM Parameter Store, and you can reference them by calling
SecretValue.secretsManager()
orSecretValue.ssmSecure()
.You can use
SecretValue.unsafePlainText()
to construct aSecretValue
from a literal string, but doing so is highly discouraged.To make sure secret values don’t accidentally end up in readable parts of your infrastructure definition (such as the environment variables of an AWS Lambda Function, where everyone who can read the function definition has access to the secret), using secret values directly is not allowed. You must pass them to constructs that accept
SecretValue
properties, which are guaranteed to use the value only in CloudFormation properties that are write-only.If you are sure that what you are doing is safe, you can call
secretValue.unsafeUnwrap()
to access the protected string of the secret value.(If you are writing something like an AWS Lambda Function and need to access a secret inside it, make the API call to
GetSecretValue
directly inside your Lamba’s code, instead of using environment variables.)- ExampleMetadata:
infused
Example:
# Read the secret from Secrets Manager pipeline = codepipeline.Pipeline(self, "MyPipeline") source_output = codepipeline.Artifact() source_action = codepipeline_actions.GitHubSourceAction( action_name="GitHub_Source", owner="awslabs", repo="aws-cdk", oauth_token=SecretValue.secrets_manager("my-github-token"), output=source_output, branch="develop" ) pipeline.add_stage( stage_name="Source", actions=[source_action] )
Construct a SecretValue (do not use!).
Do not use the constructor directly: use one of the factory functions on the class instead.
- Parameters:
protected_value (
Any
)stack_trace (
Optional
[bool
]) – Capture the stack trace of where this token is created. Default: true
Methods
- resolve(context)
Resolve the secret.
If the feature flag is not set, resolve as normal. Otherwise, throw a descriptive error that the usage guard is missing.
- Parameters:
context (
IResolveContext
)- Return type:
Any
- to_json()
Turn this Token into JSON.
Called automatically when JSON.stringify() is called on a Token.
- Return type:
Any
- to_string()
Convert an instance of this Token to a string.
This method will be called implicitly by language runtimes if the object is embedded into a string. We treat it the same as an explicit stringification.
- Return type:
str
- unsafe_unwrap()
Disable usage protection on this secret.
Call this to indicate that you want to use the secret value held by this object in an unchecked way. If you don’t call this method, using the secret value directly in a string context or as a property value somewhere will produce an error.
This method has ‘unsafe’ in the name on purpose! Make sure that the construct property you are using the returned value in is does not end up in a place in your AWS infrastructure where it could be read by anyone unexpected.
When in doubt, don’t call this method and only pass the object to constructs that accept
SecretValue
parameters.- Return type:
str
Attributes
- creation_stack
The captured stack trace which represents the location in which this token was created.
Static Methods
- classmethod cfn_dynamic_reference(ref)
Obtain the secret value through a CloudFormation dynamic reference.
If possible, use
SecretValue.ssmSecure
orSecretValue.secretsManager
directly.- Parameters:
ref (
CfnDynamicReference
) – The dynamic reference to use.- Return type:
- classmethod cfn_parameter(param)
Obtain the secret value through a CloudFormation parameter.
Generally, this is not a recommended approach. AWS Secrets Manager is the recommended way to reference secrets.
- Parameters:
param (
CfnParameter
) – The CloudFormation parameter to use.- Return type:
- classmethod is_secret_value(x)
Test whether an object is a SecretValue.
- Parameters:
x (
Any
)- Return type:
bool
- classmethod plain_text(secret)
(deprecated) Construct a literal secret value for use with secret-aware constructs.
Do not use this method for any secrets that you care about! The value will be visible to anyone who has access to the CloudFormation template (via the AWS Console, SDKs, or CLI).
The only reasonable use case for using this method is when you are testing.
- Parameters:
secret (
str
)- Deprecated:
Use
unsafePlainText()
instead.- Stability:
deprecated
- Return type:
- classmethod resource_attribute(attr)
Use a resource’s output as secret value.
- Parameters:
attr (
str
)- Return type:
- classmethod secrets_manager(secret_id, *, json_field=None, version_id=None, version_stage=None)
Creates a
SecretValue
with a value which is dynamically loaded from AWS Secrets Manager.- Parameters:
secret_id (
str
) – The ID or ARN of the secret.json_field (
Optional
[str
]) – The key of a JSON field to retrieve. This can only be used if the secret stores a JSON object. Default: - returns all the content stored in the Secrets Manager secret.version_id (
Optional
[str
]) – Specifies the unique identifier of the version of the secret you want to use. Can specify at most one ofversionId
andversionStage
. Default: AWSCURRENTversion_stage (
Optional
[str
]) – Specifies the secret version that you want to retrieve by the staging label attached to the version. Can specify at most one ofversionId
andversionStage
. Default: AWSCURRENT
- Return type:
- classmethod ssm_secure(parameter_name, version=None)
Use a secret value stored from a Systems Manager (SSM) parameter.
- Parameters:
parameter_name (
str
) – The name of the parameter in the Systems Manager Parameter Store. The parameter name is case-sensitive.version (
Optional
[str
]) – An integer that specifies the version of the parameter to use. If you don’t specify the exact version, AWS CloudFormation uses the latest version of the parameter.
- Return type:
- classmethod unsafe_plain_text(secret)
Construct a literal secret value for use with secret-aware constructs.
Do not use this method for any secrets that you care about! The value will be visible to anyone who has access to the CloudFormation template (via the AWS Console, SDKs, or CLI).
The only reasonable use case for using this method is when you are testing.
- Parameters:
secret (
str
)- Return type: