class SecretValue

Language	Type name
.NET	Amazon.CDK.SecretValue
Java	software.amazon.awscdk.core.SecretValue
Python	aws_cdk.core.SecretValue
TypeScript (source)	@aws-cdk/core » SecretValue

Implements IResolvable

Extends 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() or SecretValue.ssmSecure().

You can use SecretValue.unsafePlainText() to construct a SecretValue 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.)

Example

// Read the secret from Secrets Manager
const pipeline = new codepipeline.Pipeline(this, 'MyPipeline');
const sourceOutput = new codepipeline.Artifact();
const sourceAction = new codepipeline_actions.GitHubSourceAction({
  actionName: 'GitHub_Source',
  owner: 'awslabs',
  repo: 'aws-cdk',
  oauthToken: SecretValue.secretsManager('my-github-token'),
  output: sourceOutput,
  branch: 'develop', // default: 'master'
});
pipeline.addStage({
  stageName: 'Source',
  actions: [sourceAction],
});

Initializer

new SecretValue(protectedValue: any, options?: IntrinsicProps)

Parameters

• protectedValue any
• options IntrinsicProps

Construct a SecretValue (do not use!).

Do not use the constructor directly: use one of the factory functions on the class instead.

Properties

Name	Type	Description
creationStack	string[]	The captured stack trace which represents the location in which this token was created.

---

creationStack

Type: string[]

The captured stack trace which represents the location in which this token was created.

Methods

Name	Description
resolve(context)	Resolve the secret.
toJSON()	Turn this Token into JSON.
toString()	Convert an instance of this Token to a string.
unsafeUnwrap()	Disable usage protection on this secret.
static cfnDynamicReference(ref)	Obtain the secret value through a CloudFormation dynamic reference.
static cfnParameter(param)	Obtain the secret value through a CloudFormation parameter.
static isSecretValue(x)	Test whether an object is a SecretValue.
static plainText(secret)⚠️	Construct a literal secret value for use with secret-aware constructs.
static resourceAttribute(attr)	Use a resource's output as secret value.
static secretsManager(secretId, options?)	Creates a SecretValue with a value which is dynamically loaded from AWS Secrets Manager.
static ssmSecure(parameterName, version?)	Use a secret value stored from a Systems Manager (SSM) parameter.
static unsafePlainText(secret)	Construct a literal secret value for use with secret-aware constructs.

---

resolve(context)

public resolve(context: IResolveContext): any

Parameters

• context IResolveContext

Returns

• any

Resolve the secret.

If the feature flag is not set, resolve as normal. Otherwise, throw a descriptive error that the usage guard is missing.

---

toJSON()

public toJSON(): any

Returns

• any

Turn this Token into JSON.

Called automatically when JSON.stringify() is called on a Token.

---

toString()

public toString(): string

Returns

• 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.

---

unsafeUnwrap()

public unsafeUnwrap(): string

Returns

• string

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.

---

static cfnDynamicReference(ref)

public static cfnDynamicReference(ref: CfnDynamicReference): SecretValue

Parameters

• ref CfnDynamicReference — The dynamic reference to use.

Returns

• SecretValue

Obtain the secret value through a CloudFormation dynamic reference.

If possible, use SecretValue.ssmSecure or SecretValue.secretsManager directly.

---

static cfnParameter(param)

public static cfnParameter(param: CfnParameter): SecretValue

Parameters

• param CfnParameter — The CloudFormation parameter to use.

Returns

• SecretValue

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.

---

static isSecretValue(x)

public static isSecretValue(x: any): boolean

Parameters

• x any

Returns

• boolean

Test whether an object is a SecretValue.

---

static plainText(secret)⚠️

public static plainText(secret: string): SecretValue

⚠️ Deprecated: Use unsafePlainText() instead.

Parameters

• secret string

Returns

• SecretValue

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.

---

static resourceAttribute(attr)

public static resourceAttribute(attr: string): SecretValue

Parameters

• attr string

Returns

• SecretValue

Use a resource's output as secret value.

---

static secretsManager(secretId, options?)

public static secretsManager(secretId: string, options?: SecretsManagerSecretOptions): SecretValue

Parameters

• secretId string — The ID or ARN of the secret.
• options SecretsManagerSecretOptions — Options.

Returns

• SecretValue

Creates a SecretValue with a value which is dynamically loaded from AWS Secrets Manager.

---

static ssmSecure(parameterName, version?)

public static ssmSecure(parameterName: string, version?: string): SecretValue

Parameters

• parameterName string — The name of the parameter in the Systems Manager Parameter Store.
• version string — An integer that specifies the version of the parameter to use.

Returns

• SecretValue

Use a secret value stored from a Systems Manager (SSM) parameter.

---

static unsafePlainText(secret)

public static unsafePlainText(secret: string): SecretValue

Parameters

• secret string

Returns

• SecretValue

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.