Class SecretValue

Work with secret values in the CDK.

Inheritance
object
Intrinsic
SecretValue
Implements
Inherited Members
Namespace: Amazon.CDK
Assembly: Amazon.CDK.Lib.dll
Syntax (csharp)
public class SecretValue : Intrinsic, IResolvable
Syntax (vb)
Public Class SecretValue Inherits Intrinsic Implements IResolvable
Remarks

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

ExampleMetadata: infused

Examples
// Read the secret from Secrets Manager
             var pipeline = new Pipeline(this, "MyPipeline");
             var sourceOutput = new Artifact();
             var sourceAction = new GitHubSourceAction(new GitHubSourceActionProps {
                 ActionName = "GitHub_Source",
                 Owner = "awslabs",
                 Repo = "aws-cdk",
                 OauthToken = SecretValue.SecretsManager("my-github-token"),
                 Output = sourceOutput,
                 Branch = "develop"
             });
             pipeline.AddStage(new StageOptions {
                 StageName = "Source",
                 Actions = new [] { sourceAction }
             });

Synopsis

Constructors

SecretValue(object, IIntrinsicProps?)

Construct a SecretValue (do not use!).

Methods

CfnDynamicReference(CfnDynamicReference)

Obtain the secret value through a CloudFormation dynamic reference.
CfnDynamicReferenceKey(string, ISecretsManagerSecretOptions?)

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

Obtain the secret value through a CloudFormation parameter.
IsSecretValue(object)

Test whether an object is a SecretValue.
PlainText(string)

(deprecated) Construct a literal secret value for use with secret-aware constructs.
Resolve(IResolveContext)

Resolve the secret.
ResourceAttribute(string)

Use a resource's output as secret value.
SecretsManager(string, ISecretsManagerSecretOptions?)

Creates a SecretValue with a value which is dynamically loaded from AWS Secrets Manager.
SsmSecure(string, string?)

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

Construct a literal secret value for use with secret-aware constructs.
UnsafeUnwrap()

Disable usage protection on this secret.

Constructors

SecretValue(object, IIntrinsicProps?)

Construct a SecretValue (do not use!).

public SecretValue(object protectedValue, IIntrinsicProps? options = null)
Parameters
protectedValue object
options IIntrinsicProps
Remarks

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

Methods

CfnDynamicReference(CfnDynamicReference)

Obtain the secret value through a CloudFormation dynamic reference.

public static SecretValue CfnDynamicReference(CfnDynamicReference @ref)
Parameters
ref CfnDynamicReference

The dynamic reference to use.

Returns

SecretValue

Remarks

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

CfnDynamicReferenceKey(string, ISecretsManagerSecretOptions?)

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

public static string CfnDynamicReferenceKey(string secretId, ISecretsManagerSecretOptions? options = null)
Parameters
secretId string

The ID or ARN of the secret.

options ISecretsManagerSecretOptions

Options.

Returns

string

Remarks

See: https://docs.aws.amazon.com/secretsmanager/latest/userguide/cfn-example_reference-secret.html

CfnParameter(CfnParameter)

Obtain the secret value through a CloudFormation parameter.

public static SecretValue CfnParameter(CfnParameter param)
Parameters
param CfnParameter

The CloudFormation parameter to use.

Returns

SecretValue

Remarks

Generally, this is not a recommended approach. AWS Secrets Manager is the recommended way to reference secrets.

IsSecretValue(object)

Test whether an object is a SecretValue.

public static bool IsSecretValue(object x)
Parameters
x object
Returns

bool

Remarks

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

ExampleMetadata: infused

PlainText(string)

(deprecated) Construct a literal secret value for use with secret-aware constructs.

[Obsolete("Use `unsafePlainText()` instead.")]
public static SecretValue PlainText(string secret)
Parameters
secret string
Returns

SecretValue

Remarks

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.

Stability: Deprecated

Resolve(IResolveContext)

Resolve the secret.

public override object Resolve(IResolveContext context)
Parameters
context IResolveContext
Returns

object

Overrides
Remarks

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

ResourceAttribute(string)

Use a resource's output as secret value.

public static SecretValue ResourceAttribute(string attr)
Parameters
attr string
Returns

SecretValue

Remarks

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

ExampleMetadata: infused

SecretsManager(string, ISecretsManagerSecretOptions?)

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

public static SecretValue SecretsManager(string secretId, ISecretsManagerSecretOptions? options = null)
Parameters
secretId string

The ID or ARN of the secret.

options ISecretsManagerSecretOptions

Options.

Returns

SecretValue

Remarks

If you rotate the value in the Secret, you must also change at least one property on the resource where you are using the secret, to force CloudFormation to re-read the secret.

SsmSecure(string, string?)

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

public static SecretValue SsmSecure(string parameterName, string? version = null)
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

Remarks

This secret source in only supported in a limited set of resources and properties. Click here for the list of supported properties.

UnsafePlainText(string)

Construct a literal secret value for use with secret-aware constructs.

public static SecretValue UnsafePlainText(string secret)
Parameters
secret string
Returns

SecretValue

Remarks

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 primary use case for using this method is when you are testing.

The other use case where this is appropriate is when constructing a JSON secret. For example, a JSON secret might have multiple fields where only some are actual secret values.

Examples
SecretValue secret;

             IDictionary<string, SecretValue> jsonSecret = new Dictionary<string, SecretValue> {
                 { "username", SecretValue.UnsafePlainText("myUsername") },
                 { "password", secret }
             };

UnsafeUnwrap()

Disable usage protection on this secret.

public virtual string UnsafeUnwrap()
Returns

string

Remarks

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.

Implements