software.amazon.awscdk

Class SecretValue

java.lang.Object

software.amazon.jsii.JsiiObject

software.amazon.awscdk.Intrinsic

software.amazon.awscdk.SecretValue

All Implemented Interfaces:

IResolvable, software.amazon.jsii.JsiiSerializable

@Generated(value="jsii-pacmak/1.67.0 (build 2c027f5)",
           date="2022-09-19T20:26:35.928Z")
 @Stability(value=Stable)
public class SecretValue
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:

 App amplifyApp = App.Builder.create(this, "MyApp")
         .sourceCodeProvider(GitHubSourceCodeProvider.Builder.create()
                 .owner("<user>")
                 .repository("<repo>")
                 .oauthToken(SecretValue.secretsManager("my-github-token"))
                 .build())
         .basicAuth(BasicAuth.fromCredentials("username", SecretValue.secretsManager("my-github-token")))
         .build();
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SecretValue.Builder A fluent builder for SecretValue.

Nested classes/interfaces inherited from class software.amazon.jsii.JsiiObject

software.amazon.jsii.JsiiObject.InitializationMode

Nested classes/interfaces inherited from interface software.amazon.awscdk.IResolvable

IResolvable.Jsii$Default, IResolvable.Jsii$Proxy

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SecretValue(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)
protected	SecretValue(software.amazon.jsii.JsiiObjectRef objRef)
	SecretValue(Object protectedValue) Construct a SecretValue (do not use!).
	SecretValue(Object protectedValue, IntrinsicProps options) Construct a SecretValue (do not use!).

Method Summary

Modifier and Type	Method and Description
static SecretValue	cfnDynamicReference(CfnDynamicReference ref) Obtain the secret value through a CloudFormation dynamic reference.
static SecretValue	cfnParameter(CfnParameter param) Obtain the secret value through a CloudFormation parameter.
static Boolean	isSecretValue(Object x) Test whether an object is a SecretValue.
static SecretValue	plainText(String secret) Deprecated. Use `unsafePlainText()` instead.
Object	resolve(IResolveContext context) Resolve the secret.
static SecretValue	resourceAttribute(String attr) Use a resource's output as secret value.
static SecretValue	secretsManager(String secretId) Creates a `SecretValue` with a value which is dynamically loaded from AWS Secrets Manager.
static SecretValue	secretsManager(String secretId, SecretsManagerSecretOptions options) Creates a `SecretValue` with a value which is dynamically loaded from AWS Secrets Manager.
static SecretValue	ssmSecure(String parameterName) Use a secret value stored from a Systems Manager (SSM) parameter.
static SecretValue	ssmSecure(String parameterName, String version) Use a secret value stored from a Systems Manager (SSM) parameter.
static SecretValue	unsafePlainText(String secret) Construct a literal secret value for use with secret-aware constructs.
String	unsafeUnwrap() Disable usage protection on this secret.

Methods inherited from class software.amazon.awscdk.Intrinsic

getCreationStack, newError, toJSON, toString, toStringList

Methods inherited from class software.amazon.jsii.JsiiObject

jsiiAsyncCall, jsiiAsyncCall, jsiiCall, jsiiCall, jsiiGet, jsiiGet, jsiiSet, jsiiStaticCall, jsiiStaticCall, jsiiStaticGet, jsiiStaticGet, jsiiStaticSet, jsiiStaticSet

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface software.amazon.jsii.JsiiSerializable

$jsii$toJson

Constructor Detail

SecretValue

protected SecretValue(software.amazon.jsii.JsiiObjectRef objRef)

SecretValue

protected SecretValue(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)

SecretValue

@Stability(value=Stable)
public SecretValue(@NotNull
                                            Object protectedValue,
                                            @Nullable
                                            IntrinsicProps options)

Construct a SecretValue (do not use!).

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

Parameters:

protectedValue - This parameter is required.

options -

SecretValue

@Stability(value=Stable)
public SecretValue(@NotNull
                                            Object protectedValue)

Construct a SecretValue (do not use!).

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

Parameters:

protectedValue - This parameter is required.

Method Detail

cfnDynamicReference

@Stability(value=Stable)
 @NotNull
public static SecretValue cfnDynamicReference(@NotNull
                                                                                 CfnDynamicReference ref)

Obtain the secret value through a CloudFormation dynamic reference.

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

Parameters:

ref - The dynamic reference to use. This parameter is required.

cfnParameter

@Stability(value=Stable)
 @NotNull
public static SecretValue cfnParameter(@NotNull
                                                                          CfnParameter 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 - The CloudFormation parameter to use. This parameter is required.

isSecretValue

@Stability(value=Stable)
 @NotNull
public static Boolean isSecretValue(@NotNull
                                                                       Object x)

Test whether an object is a SecretValue.

Parameters:

x - This parameter is required.

plainText

@Stability(value=Deprecated)
 @Deprecated
 @NotNull
public static SecretValue plainText(@NotNull
                                                                                        String secret)

Deprecated. Use `unsafePlainText()` instead.

(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 - This parameter is required.

resourceAttribute

@Stability(value=Stable)
 @NotNull
public static SecretValue resourceAttribute(@NotNull
                                                                               String attr)

Use a resource's output as secret value.

Parameters:

attr - This parameter is required.

secretsManager

@Stability(value=Stable)
 @NotNull
public static SecretValue secretsManager(@NotNull
                                                                            String secretId,
                                                                            @Nullable
                                                                            SecretsManagerSecretOptions options)

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

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.

Parameters:

secretId - The ID or ARN of the secret. This parameter is required.

options - Options.

secretsManager

@Stability(value=Stable)
 @NotNull
public static SecretValue secretsManager(@NotNull
                                                                            String secretId)

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

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.

Parameters:

secretId - The ID or ARN of the secret. This parameter is required.

ssmSecure

@Stability(value=Stable)
 @NotNull
public static SecretValue ssmSecure(@NotNull
                                                                       String parameterName,
                                                                       @Nullable
                                                                       String version)

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

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

Parameters:

parameterName - The name of the parameter in the Systems Manager Parameter Store. This parameter is required.

version - An integer that specifies the version of the parameter to use.

ssmSecure

@Stability(value=Stable)
 @NotNull
public static SecretValue ssmSecure(@NotNull
                                                                       String parameterName)

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

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

Parameters:

parameterName - The name of the parameter in the Systems Manager Parameter Store. This parameter is required.

unsafePlainText

@Stability(value=Stable)
 @NotNull
public static SecretValue unsafePlainText(@NotNull
                                                                             String 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 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.

Example:

 // Example automatically generated from non-compiling source. May contain errors.
 SecretValue secret;
 Map<String, SecretValue> jsonSecret = Map.of(
         "username", SecretValue.unsafePlainText("myUsername"),
         "password", secret);
 

Parameters:

secret - This parameter is required.

resolve

@Stability(value=Stable)
 @NotNull
public Object resolve(@NotNull
                                                         IResolveContext 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.

Specified by:

resolve in interface IResolvable

Overrides:

resolve in class Intrinsic

Parameters:

context - This parameter is required.

unsafeUnwrap

@Stability(value=Stable)
 @NotNull
public String unsafeUnwrap()

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.