feat(secretsmanager): create secrets with specified values (#18098)

Enables customers to supply their own secret value in the cases where an auto-
generated value is not viable. The secret value is typed to highlight the
inheret lack of safety with creating secret values via CloudFormation; if a
plaintext secret is provided, this secret will be visible anywhere the
CloudFormation template is, including the AWS Console, SDKs, and CLIs.

An unsafe `fromUnsafePlaintext` method and slightly safer `fromToken` method are
exposed to highlight the potential risks and hopefully encourage safe usage.
The latter is intended to be used directly with a Ref or GetAtt call from
another (Custom) Resource, such as storing the value of a User SecretAccessKey
or storing a password generated from a custom resource.

As an implementation detail, this API has been created using the new standard
for experimental APIs, via suffixing with `Beta1`. This allow us to make
breaking changes by deprecating the `Beta1` version and creating an improved
`Beta2` version. I've chosen to do this in this case because this has been a
relatively controversial feature to decide to implement, and the criteria for
what makes a secret "safe" may evolve over time. I am open to feedback on
whether this is necessitated.

fixes #5810


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: njlynch

packages/@aws-cdk/aws-secretsmanager/README.md

@@ -21,12 +21,26 @@ import * as secretsmanager from '@aws-cdk/aws-secretsmanager';
 In order to have SecretsManager generate a new secret value automatically,
 you can get started with the following:
 
-[example of creating a secret](test/integ.secret.lit.ts)
-
-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).
+```ts
+// Default secret
+const secret = new secretsmanager.Secret(this, 'Secret');
+// Using the default secret
+new iam.User(this, 'User', {
+  password: secret.secretValue,
+});
+// Templated secret
+const templatedSecret = new secretsmanager.Secret(this, 'TemplatedSecret', {
+  generateSecretString: {
+    secretStringTemplate: JSON.stringify({ username: 'user' }),
+    generateStringKey: 'password',
+  },
+});
+// Using the templated secret
+new iam.User(this, 'OtherUser', {
+  userName: templatedSecret.secretValueFromJson('username').toString(),
+  password: templatedSecret.secretValueFromJson('password'),
+});
+```
 
 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`

packages/@aws-cdk/aws-secretsmanager/lib/secret.ts

@@ -115,6 +115,8 @@ export interface SecretProps {
   /**
    * Configuration for how to generate a secret value.
    *
+   * Only one of `secretString` and `generateSecretString` can be provided.
+   *
    * @default - 32 characters with upper-case letters, lower-case letters, punctuation and numbers (at least one from each
    * category), per the default values of ``SecretStringGenerator``.
    */
@@ -128,6 +130,24 @@ export interface SecretProps {
    */
   readonly secretName?: string;
 
+  /**
+   * Initial value for the secret
+   *
+   * **NOTE:** *It is **highly** encouraged to leave this field undefined and allow SecretsManager to create the secret value.
+   * The secret string -- if provided -- will be included in the output of the cdk as part of synthesis,
+   * and will appear in the CloudFormation template in the console. This can be secure(-ish) if that value is merely reference to
+   * another resource (or one of its attributes), but if the value is a plaintext string, it will be visible to anyone with access
+   * to the CloudFormation template (via the AWS Console, SDKs, or CLI).
+   *
+   * Specifies text data that you want to encrypt and store in this new version of the secret.
+   * May be a simple string value, or a string representation of a JSON structure.
+   *
+   * Only one of `secretString` and `generateSecretString` can be provided.
+   *
+   * @default - SecretsManager generates a new secret value.
+   */
+  readonly secretStringBeta1?: SecretStringValueBeta1;
+
   /**
    * Policy to apply when the secret is removed from this stack.
    *
@@ -160,6 +180,64 @@ export interface ReplicaRegion {
   readonly encryptionKey?: kms.IKey;
 }
 
+/**
+ * An experimental class used to specify an initial secret value for a Secret.
+ * The class wraps a simple string (or JSON representation) in order to provide some safety checks and warnings
+ * about the dangers of using plaintext strings as initial secret seed values via CDK/CloudFormation.
+ */
+export class SecretStringValueBeta1 {
+
+  /**
+   * Creates a `SecretStringValueBeta1` from a plaintext value.
+   * This approach is inherently unsafe, as the secret value may be visible in your source control repository
+   * and will also appear in plaintext in the resulting CloudFormation template, including in the AWS Console or APIs.
+   * Usage of this method is discouraged, especially for production workloads.
+   */
+  public static fromUnsafePlaintext(secretValue: string) { return new SecretStringValueBeta1(secretValue); }
+
+  /**
+   * Creates a `SecretValueValueBeta1` from a string value coming from a Token.
+   * The intent is to enable creating secrets from references (e.g., `Ref`, `Fn::GetAtt`) from other resources.
+   * This might be the direct output of another Construct, or the output of a Custom Resource.
+   * This method throws if it determines the input is an unsafe plaintext string.
+   *
+   * For example:
+   * ```ts
+   *     // Creates a new IAM user, access and secret keys, and stores the secret access key in a Secret.
+   *     const user = new iam.User(this, 'User');
+   *     const accessKey = new iam.CfnAccessKey(this, 'AccessKey', { userName: user.userName });
+   *     const secretValue = secretsmanager.SecretStringValueBeta1.fromToken(accessKey.attrSecretAccessKey);
+   *     new secretsmanager.Secret(this, 'Secret', {
+   *       secretStringBeta1: secretValue,
+   *     });
+   * ```
+   *
+   * The secret may also be embedded in a string representation of a JSON structure:
+   *     const secretValue = secretsmanager.SecretStringValueBeta1.fromToken(JSON.stringify({
+   *       username: user.userName,
+   *       database: 'foo',
+   *       password: accessKey.attrSecretAccessKey
+   *     }));
+   *
+   * Note that the value being a Token does *not* guarantee safety. For example, a Lazy-evaluated string
+   * (e.g., `Lazy.string({ produce: () => 'myInsecurePassword' }))`) is a Token, but as the output is
+   * ultimately a plaintext string, and so insecure.
+   *
+   * @param secretValueFromToken a secret value coming from a Construct attribute or Custom Resource output
+   */
+  public static fromToken(secretValueFromToken: string) {
+    if (!Token.isUnresolved(secretValueFromToken)) {
+      throw new Error('SecretStringValueBeta1 appears to be plaintext (unsafe) string (or resolved Token); use fromUnsafePlaintext if this is intentional');
+    }
+    return new SecretStringValueBeta1(secretValueFromToken);
+  }
+
+  private constructor(private readonly _secretValue: string) { }
+
+  /** Returns the secret value */
+  public secretValue(): string { return this._secretValue; }
+}
+
 /**
  * Attributes required to import an existing secret into the Stack.
  * One ARN format (`secretArn`, `secretCompleteArn`, `secretPartialArn`) must be provided.
@@ -459,10 +537,15 @@ export class Secret extends SecretBase {
       throw new Error('`secretStringTemplate` and `generateStringKey` must be specified together.');
     }
 
+    if (props.generateSecretString && props.secretStringBeta1) {
+      throw new Error('Cannot specify both `generateSecretString` and `secretStringBeta1`.');
+    }
+
     const resource = new secretsmanager.CfnSecret(this, 'Resource', {
       description: props.description,
       kmsKeyId: props.encryptionKey && props.encryptionKey.keyArn,
-      generateSecretString: props.generateSecretString || {},
+      generateSecretString: props.generateSecretString ?? (props.secretStringBeta1 ? undefined : {}),
+      secretString: props.secretStringBeta1?.secretValue(),
       name: this.physicalName,
       replicaRegions: Lazy.any({ produce: () => this.replicaRegions }, { omitEmptyArray: true }),
     });

packages/@aws-cdk/aws-secretsmanager/test/integ.secret.lit.expected.json

@@ -126,6 +126,27 @@
           ]
         }
       }
+    },
+    "AccessKey": {
+      "Type": "AWS::IAM::AccessKey",
+      "Properties": {
+        "UserName": {
+          "Ref": "User00B015A1"
+        }
+      }
+    },
+    "PredefinedSecret660AF4EC": {
+      "Type": "AWS::SecretsManager::Secret",
+      "Properties": {
+        "SecretString": {
+          "Fn::GetAtt": [
+            "AccessKey",
+            "SecretAccessKey"
+          ]
+        }
+      },
+      "UpdateReplacePolicy": "Delete",
+      "DeletionPolicy": "Delete"
     }
   }
 }

packages/@aws-cdk/aws-secretsmanager/test/integ.secret.lit.ts

@@ -13,7 +13,7 @@ class SecretsManagerStack extends cdk.Stack {
     const secret = new secretsmanager.Secret(this, 'Secret');
     secret.grantRead(role);
 
-    new iam.User(this, 'User', {
+    const user = new iam.User(this, 'User', {
       password: secret.secretValue,
     });
 
@@ -29,6 +29,12 @@ class SecretsManagerStack extends cdk.Stack {
       userName: templatedSecret.secretValueFromJson('username').toString(),
       password: templatedSecret.secretValueFromJson('password'),
     });
+
+    // Secret with predefined value
+    const accessKey = new iam.CfnAccessKey(this, 'AccessKey', { userName: user.userName });
+    new secretsmanager.Secret(this, 'PredefinedSecret', {
+      secretStringBeta1: secretsmanager.SecretStringValueBeta1.fromToken(accessKey.attrSecretAccessKey),
+    });
     /// !hide
   }
 }

packages/@aws-cdk/aws-secretsmanager/test/secret.test.ts

@@ -1,5 +1,5 @@
 import '@aws-cdk/assert-internal/jest';
-import { expect as assertExpect, ResourcePart } from '@aws-cdk/assert-internal';
+import { ABSENT, expect as assertExpect, ResourcePart } from '@aws-cdk/assert-internal';
 import * as iam from '@aws-cdk/aws-iam';
 import * as kms from '@aws-cdk/aws-kms';
 import * as lambda from '@aws-cdk/aws-lambda';
@@ -178,6 +178,94 @@ test('templated secret string', () => {
   });
 });
 
+describe('secretStringBeta1', () => {
+  let user: iam.User;
+  let accessKey: iam.CfnAccessKey;
+
+  beforeEach(() => {
+    user = new iam.User(stack, 'User');
+    accessKey = new iam.CfnAccessKey(stack, 'MyKey', { userName: user.userName });
+  });
+
+  test('fromUnsafePlaintext allows specifying a plaintext string', () => {
+    new secretsmanager.Secret(stack, 'Secret', {
+      secretStringBeta1: secretsmanager.SecretStringValueBeta1.fromUnsafePlaintext('unsafeP@$$'),
+    });
+
+    expect(stack).toHaveResource('AWS::SecretsManager::Secret', {
+      GenerateSecretString: ABSENT,
+      SecretString: 'unsafeP@$$',
+    });
+  });
+
+  test('toToken throws when provided an unsafe plaintext string', () => {
+    expect(() => new secretsmanager.Secret(stack, 'Secret', {
+      secretStringBeta1: secretsmanager.SecretStringValueBeta1.fromToken('unsafeP@$$'),
+    })).toThrow(/appears to be plaintext/);
+  });
+
+  test('toToken allows referencing a construct attribute', () => {
+    new secretsmanager.Secret(stack, 'Secret', {
+      secretStringBeta1: secretsmanager.SecretStringValueBeta1.fromToken(accessKey.attrSecretAccessKey),
+    });
+
+    expect(stack).toHaveResource('AWS::SecretsManager::Secret', {
+      GenerateSecretString: ABSENT,
+      SecretString: { 'Fn::GetAtt': ['MyKey', 'SecretAccessKey'] },
+    });
+  });
+
+  test('toToken allows referencing a construct attribute in nested JSON', () => {
+    const secretString = secretsmanager.SecretStringValueBeta1.fromToken(JSON.stringify({
+      key: accessKey.attrSecretAccessKey,
+      username: 'myUser',
+    }));
+    new secretsmanager.Secret(stack, 'Secret', {
+      secretStringBeta1: secretString,
+    });
+
+    expect(stack).toHaveResource('AWS::SecretsManager::Secret', {
+      GenerateSecretString: ABSENT,
+      SecretString: {
+        'Fn::Join': [
+          '',
+          [
+            '{"key":"',
+            {
+              'Fn::GetAtt': [
+                'MyKey',
+                'SecretAccessKey',
+              ],
+            },
+            '","username":"myUser"}',
+          ],
+        ],
+      },
+    });
+  });
+
+  test('toToken throws if provided a resolved token', () => {
+    // NOTE - This is actually not desired behavior, but the simple `!Token.isUnresolved`
+    // check is the simplest and most consistent to implement. Covering this edge case of
+    // a resolved Token representing a Ref/Fn::GetAtt is out of scope for this initial pass.
+    const secretKey = stack.resolve(accessKey.attrSecretAccessKey);
+    expect(() => new secretsmanager.Secret(stack, 'Secret', {
+      secretStringBeta1: secretsmanager.SecretStringValueBeta1.fromToken(secretKey),
+    })).toThrow(/appears to be plaintext/);
+  });
+
+  test('throws if both generateSecretString and secretStringBeta1 are provided', () => {
+    expect(() => new secretsmanager.Secret(stack, 'Secret', {
+      generateSecretString: {
+        generateStringKey: 'username',
+        secretStringTemplate: JSON.stringify({ username: 'username' }),
+      },
+      secretStringBeta1: secretsmanager.SecretStringValueBeta1.fromToken(accessKey.attrSecretAccessKey),
+    })).toThrow(/Cannot specify both `generateSecretString` and `secretStringBeta1`./);
+  });
+
+});
+
 test('grantRead', () => {
   // GIVEN
   const key = new kms.Key(stack, 'KMS');