feat(docdb): add managed password support by mazyu36 · Pull Request #35711 · aws/aws-cdk

mazyu36 · 2025-10-10T04:43:29Z

Issue # (if applicable)

Closes #.

Reason for this change

This change adds support for AWS Secrets Manager managed passwords in DocumentDB clusters.
This feature provides enhanced security by allowing AWS DocumentDB to automatically generate, manage, and rotate master user passwords using AWS Secrets Manager, eliminating the need for manual password management.

Description of changes

manageMasterUserPassword: boolean - Enables AWS Secrets Manager to manage the master user password
masterUserSecretKmsKey: kms.IKey - Specifies a custom KMS key to encrypt the managed secret
rotateMasterUserPassword: boolean - Triggers immediate password rotation for managed secrets

Describe any new or updated permissions being added

Description of how you validated changes

Add unit tests and an integ test.

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

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

github-actions · 2026-01-20T06:27:09Z

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
Please try merge from main to avoid findings unrelated to the PR.

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results	48 ran	48 passed

Test	Result
No test annotations available

View Security Guardian Results

github-actions · 2026-01-20T06:27:11Z

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
Please try merge from main to avoid findings unrelated to the PR.

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results with resolved templates	48 ran	48 passed

Test	Result
No test annotations available

View Security Guardian Results with resolved templates

gudipati · 2026-06-23T09:52:52Z

-    // Create the secret manager secret if no password is specified
+    // Validate manageMasterUserPassword constraints
+    if (props.manageMasterUserPassword && props.masterUser.password) {
+      throw new ValidationError('You can\'t manage the master user password with AWS Secrets Manager if masterUser.password is specified', this);
+    }
+
+    if (props.masterUserSecretKmsKey && !props.manageMasterUserPassword) {
+      throw new ValidationError('masterUserSecretKmsKey is valid only if manageMasterUserPassword is true', this);
+    }
+
+    if (props.rotateMasterUserPassword && !props.manageMasterUserPassword) {
+      throw new ValidationError('rotateMasterUserPassword is valid only if manageMasterUserPassword is true', this);
+    }


These ValidationError calls are missing the lit tagged template error code that all other ValidationError calls in this file use. This enforces compile-time literal error codes for structured error handling.

For reference, see line 519:

throw new ValidationError(lit\`InstanceTypeOrServerlessConfigurationRequired\`, '...', this);

gudipati · 2026-06-23T09:59:03Z

+   * Specifies whether to rotate the secret managed by AWS Secrets Manager for the master user password.
+   *
+   * This setting is valid only if the master user password is managed by Amazon DocumentDB in AWS Secrets Manager for the cluster.
+   * The secret value contains the updated password.
+   *
+   * When you rotate the master user password, the change must be applied immediately.


Does this property only trigger a one-time rotation ?

If yes, could we update this JSDoc to be clearer:

/** * Specifies whether to trigger an immediate one-time rotation of the master user password * managed by AWS Secrets Manager. * * This does NOT establish automatic scheduled rotation - Amazon DocumentDB automatically * rotates the managed secret every 7 days by default. Set this to `true` to trigger * an additional immediate rotation during the current cluster update. * * This setting is valid only if `manageMasterUserPassword` is true. * * @see https://docs.aws.amazon.com/documentdb/latest/devguide/docdb-secrets-manager.html * @default false */

Yes, it's a one-time immediate rotation. One additional finding: RotateMasterUserPassword exists only on ModifyDBCluster (not on CreateDBCluster), so it has no effect at cluster creation — I confirmed via CloudTrail that creation events are identical with and without the flag (the rotation observed right after creation is part of the managed secret initialization). Updated the JSDoc based on your suggestion with this addition, and adjusted the README example to apply the flag to an existing cluster.

gudipati · 2026-06-23T10:00:22Z

+  /**
+   * The AWS KMS key to encrypt a secret that is automatically generated and managed in AWS Secrets Manager.
+   *
+   * This setting is valid only if the master user password is managed by Amazon DocumentDB in AWS Secrets Manager for the DB cluster.


nit: Maybe we can make this clearer -
This setting is valid only if the master user password is managed by Amazon DocumentDB in AWS Secrets Manager for the DB cluster (i.e. when manageMasterUserPassword is true).

Clarified as suggested.

gudipati · 2026-06-23T10:00:52Z

+   *
+   * This setting is valid only if the master user password is managed by Amazon DocumentDB in AWS Secrets Manager for the DB cluster.
+   * If you don't specify this property, then the `aws/secretsmanager` KMS key is used to encrypt the secret.
+   *


can we add the documentation link -

* @see https://docs.aws.amazon.com/documentdb/latest/devguide/docdb-secrets-manager.html

gudipati · 2026-06-23T10:00:58Z

+   * This provides enhanced security and automatic password rotation capabilities.
+   *
+   * Constraint: You can't manage the master user password with AWS Secrets Manager if `masterUser.password` is specified.
+   *


can we add the documentation link -

* @see https://docs.aws.amazon.com/documentdb/latest/devguide/docdb-secrets-manager.html

gudipati · 2026-06-23T10:03:33Z

+
+new IntegTest(app, 'aws-cdk-docdb-cluster-managed-password-integ', {
+  testCases: [stack],
+});


Could we also verify that the managed secret was created using an awsApiCall assertion (for e.g., DescribeDBClusters to check MasterUserSecret is populated) ?

gudipati · 2026-06-23T12:24:35Z

    if (secret) {
      this.secret = secret.attach(this);
    }


When manageMasterUserPassword is true, the this.secret property remains undefined, which means users cannot use cluster.secret?.grantRead(role) to grant their applications access to the managed credential.

CloudFormation exposes the managed secret ARN via AWS::DocDB::DBCluster attribute MasterUserSecret.SecretArn. Could we expose it so users can use grants on it?

if (secret) { this.secret = secret.attach(this); } else if (props.manageMasterUserPassword) { this.secret = secretsmanager.Secret.fromSecretCompleteArn( this, 'ManagedSecret', this.cluster.attrMasterUserSecretSecretArn, ); }

I investigated, and this turned out not to be implementable this way: unlike RDS, AWS::DocDB::DBCluster does not support Fn::GetAtt for MasterUserSecret.SecretArn (confirmed in both the CFN resource spec and the docs), so attrMasterUserSecretSecretArn does not exist on the L1. I also verified on a real cluster that the secret name is rds!cluster-<random UUID>, so the ARN cannot be constructed from CFN-accessible attributes either.

Instead, I documented a deploy-time lookup using AwsCustomResource in the README (the same approach cloudfront-origins takes for the VPC origin security group, whose id CloudFormation doesn't provide) and verified it works with a real deployment.

gudipati · 2026-06-23T12:38:09Z

+        ManageMasterUserPassword: true,
+        MasterUsername: 'admin',
+        MasterUserPassword: Match.absent(),
+      });


When manageMasterUserPassword is true, the construct should skip creating its own secret (DatabaseSecret) - let's add an assertion to verify that AWS::SecretsManager::Secret resource is not created:

Template.fromStack(stack).resourceCountIs('AWS::SecretsManager::Secret', 0);

gudipati · 2026-06-23T12:39:56Z


+## AWS Secrets Manager Integration
+
+DocumentDB clusters can integrate with AWS Secrets Manager to automatically manage master user passwords. This provides enhanced security through automatic password generation and rotation capabilities.


We can add these details to make it clearer:

Note: By default, CDK creates and manages a Secrets Manager secret for the master password (with rotation via Lambda functions using addRotationSingleUser()). The manageMasterUserPassword option delegates password management entirely to the DocumentDB service, which includes built-in automatic rotation every 7 days without requiring Lambda functions.

Added. One adjustment: rotation of the default secret is not automatic — it must be configured explicitly with addRotationSingleUser() — so I worded that part accordingly.

Have you tested this ?

Does the user need to use addRotationSingleUser to enable rotation of the managed secret ? If yes, currently addRotationSingleUser or addRotationMultiUser will not work if manageMasterUserPassword is true because this.secret will be undefined - https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-docdb/lib/cluster.ts#L741

How do we provide users a way to enable rotation ?

That README sentence describes the default setup where the construct creates the secret. In that case this.secret is set and addRotationSingleUser() works.

For the managed secret, addRotationSingleUser() is not needed. Rotation is enabled from the start and the service rotates the password every 7 days (see How Amazon DocumentDB uses AWS Secrets Manager).

You are right that calling addRotationSingleUser() / addRotationMultiUser() with manageMasterUserPassword: true fails with a misleading message. I added the same dedicated validation error as the RDS L2.

gudipati · 2026-06-23T13:00:30Z

+        (secret ? secret.secretValueFromJson('password').unsafeUnwrap() : props.masterUser.password!.unsafeUnwrap()),
+      // ManageMasterUserPassword
+      manageMasterUserPassword: props.manageMasterUserPassword,
+      masterUserSecretKmsKeyId: props.masterUserSecretKmsKey?.keyArn,


Could you verify if masterUserSecretKmsKey needs to grant KMS permissions to Secrets Manager service principal for runtime credential retrieval by creating the cluster and trying some operations on it ? If yes, we would need to add something like this (with the appropriate scoped-down permissions) - https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-secretsmanager/lib/secret.ts#L732-L735

Verified on a real cluster. With a CMK whose key policy is the default (account root only), both secret creation and rotation succeeded without any key policy changes. Service-managed secrets work through KMS grants that the service creates on the key itself, so the grants in secret.ts:732-735 (which are for CDK-owned secrets) aren't needed here. The RDS L2 likewise adds nothing for manageMasterUserPassword.

gudipati · 2026-07-13T10:35:23Z

@mazyu36 Any update on this PR ?

mazyu36 · 2026-07-13T10:58:53Z

@gudipati Sorry, I hadn’t gotten to this yet. I’ll address your review comments soon.

gasolima · 2026-07-28T14:37:39Z

+   * module README for how to access the managed secret.
+   *
+   * @see https://docs.aws.amazon.com/documentdb/latest/developerguide/docdb-secrets-manager.html
+   * @default false


What's the reason for not making the default behaviour the service to manage the password?

Managed passwords are not a strict superset of the existing behavior, so this is opt-in. The construct-created secret has capabilities the managed one does not: you can set the secret name and excluded characters, choose the rotation interval with addRotationSingleUser(), use alternating-user rotation with addRotationMultiUser(), and it works with global databases and cross-Region read replicas (managed passwords are not supported for those configurations).

Switching the default would also change the behavior of existing stacks, so it would need a feature flag.

Yes totally agree that there's a use case for the non managed one over the managed one, but have a feeling the one who will use the non managed one is more advanced user that will be aware of all of that, so they will have enough knowledge to explicitly choose what they want vs the beginner user who doesn't want to go in all those complications.

Yes it needs a feature flag, since it's anyway if we did it now or in the future we will need a feature flag, we can leave this one out.

gasolima · 2026-07-28T14:41:05Z

+   * @see https://docs.aws.amazon.com/documentdb/latest/developerguide/docdb-secrets-manager.html
+   * @default false
+   */
+  readonly rotateMasterUserPassword?: boolean;


Is there any useful use case for this option? If not i prefer to leave it for the future, just to make it easier for customers to understand this interface since a lot of those props depend on each other which make it very mental exhausting to understand what to choose

What i mean by depend on each other rotateMasterUserPassword needs to have manageMasterUserPassword then manageMasterUserPassword needs to not pass password, etc...

Agreed, I removed it from this PR. The property maps to a modify-only API parameter, so it has no effect at cluster creation, and its only use is forcing a one-time rotation on an existing cluster. We can add it in a separate PR if there is demand for it.

mergify · 2026-08-05T09:08:24Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

Pull request has been modified.

mergify · 2026-08-11T15:05:41Z

Merge Queue Status

✅ Entered queue — 2026-08-05 09:08 UTC · Rule: default-squash · triggered by rule automatic merge
🚫 Left the queue — 2026-08-05 09:08 UTC · at eb6b941f5b71b8fa18f57a74af29f6dd49ab379e

This pull request spent 12 seconds in the queue, with no time running CI.

Reason

The pull request can't be updated

For security reasons, Mergify can't update this pull request. Try updating locally.
GitHub response: refusing to allow a GitHub App to create or update workflow .github/workflows/README.md without workflows permission

Hint

You should update or rebase your pull request manually. If you do, this pull request will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue, you can requeue the pull request, without updating it, by posting a @mergifyio queue comment.

Requeued — the merge queue status continues in this comment ↓.

mergify · 2026-08-11T15:05:44Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2026-08-11T15:05:51Z

Merge Queue Status

✅ Entered queue — 2026-08-11 15:05 UTC · Rule: default-squash · triggered by rule automatic merge
✅ Checks passed · in-place
✅ Merged — 2026-08-11 17:35 UTC · at 7651609f91c226b1b32913b8825fb10936192f5b · squash

This pull request spent 2 hours 29 minutes 25 seconds in the queue, including 56 minutes 16 seconds running CI.

Required conditions to merge

github-review-approved [🛡 GitHub branch protection]
- feat(docdb): add managed password support #35711
any of [🛡 GitHub branch protection]:
- check-success = validate-pr
- check-neutral = validate-pr
- check-skipped = validate-pr
any of [🛡 GitHub branch protection]:
- check-success = build
- check-neutral = build
- check-skipped = build

mergify · 2026-08-11T15:55:59Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2026-08-11T17:34:56Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

github-actions · 2026-08-11T17:35:20Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

github-actions Bot added the p2 label Oct 10, 2025

aws-cdk-automation requested a review from a team October 10, 2025 04:43

github-actions Bot added the distinguished-contributor [Pilot] contributed 50+ PRs to the CDK label Oct 10, 2025

mazyu36 changed the title ~~feat(docdb): add managed password support~~ feat(docdb): add managed password support Oct 10, 2025

aws-cdk-automation added the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label Oct 10, 2025

badmintoncryer approved these changes Oct 13, 2025

View reviewed changes

aws-cdk-automation added pr/needs-maintainer-review This PR needs a review from a Core Team Member and removed pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. labels Oct 13, 2025

github-actions Bot mentioned this pull request Nov 1, 2025

Monthly PR metrics report #35917

Open

aws-cdk-automation added the pr/needs-further-review PR requires additional review from our team specialists due to the scope or complexity of changes. label Jan 20, 2026

pahud mentioned this pull request Jan 20, 2026

Failed CodeBuild CI - 9 PR(s) pahud/aws-cdk#17

Open

vishaalmehrishi self-assigned this Mar 26, 2026

vishaalmehrishi assigned gudipati and unassigned vishaalmehrishi Jun 18, 2026

gudipati reviewed Jun 23, 2026

View reviewed changes

mazyu36 temporarily deployed to automation July 15, 2026 11:01 — with GitHub Actions Inactive

mazyu36 temporarily deployed to automation July 15, 2026 11:02 — with GitHub Actions Inactive

mazyu36 temporarily deployed to automation July 15, 2026 12:06 — with GitHub Actions Inactive

mazyu36 temporarily deployed to automation July 21, 2026 14:39 — with GitHub Actions Inactive

mazyu36 temporarily deployed to automation July 21, 2026 14:40 — with GitHub Actions Inactive

gasolima reviewed Jul 28, 2026

View reviewed changes

mazyu36 temporarily deployed to automation July 30, 2026 15:16 — with GitHub Actions Inactive

gasolima previously approved these changes Aug 5, 2026

View reviewed changes

gudipati force-pushed the feat/docdb-managed-password branch from 40d5d14 to 3c98cac Compare August 11, 2026 13:36

gudipati temporarily deployed to automation August 11, 2026 13:36 — with GitHub Actions Inactive

gudipati previously approved these changes Aug 11, 2026

View reviewed changes

mazyu36 added 8 commits August 11, 2026 19:56

feat(docdb): add managed password support

a95f591

fix

4f17a9b

fix

04d4fe8

fix

2619380

address review comments

1a02fb6

simplify docs and use official service name

e8fd9a9

add validation error for rotation methods with managed password

ead1ede

remove rotateMasterUserPassword

1a785d6

gudipati force-pushed the feat/docdb-managed-password branch from 3c98cac to 1a785d6 Compare August 11, 2026 14:26

gudipati temporarily deployed to automation August 11, 2026 14:26 — with GitHub Actions Inactive

gudipati approved these changes Aug 11, 2026

View reviewed changes

aws-cdk-automation removed the pr/needs-maintainer-review This PR needs a review from a Core Team Member label Aug 11, 2026

aws-cdk-automation temporarily deployed to automation August 11, 2026 15:06 — with GitHub Actions Inactive

Merge branch 'main' into feat/docdb-managed-password

7651609

mergify Bot temporarily deployed to automation August 11, 2026 16:38 Inactive

mergify Bot temporarily deployed to automation August 11, 2026 16:43 Inactive

mergify Bot merged commit fcf54bf into aws:main Aug 11, 2026
19 of 20 checks passed

github-actions Bot locked as resolved and limited conversation to collaborators Aug 11, 2026


		## AWS Secrets Manager Integration

		DocumentDB clusters can integrate with AWS Secrets Manager to automatically manage master user passwords. This provides enhanced security through automatic password generation and rotation capabilities.

Conversation

mazyu36 commented Oct 10, 2025

Issue # (if applicable)

Reason for this change

Description of changes

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

github-actions Bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gudipati commented Jul 13, 2026

Uh oh!

mazyu36 commented Jul 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mergify Bot commented Aug 5, 2026

Uh oh!

mergify Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Reason

Hint

github-actions Bot commented Jan 20, 2026 •

edited

Loading

github-actions Bot commented Jan 20, 2026 •

edited

Loading

mergify Bot commented Aug 11, 2026 •

edited

Loading

mergify Bot commented Aug 11, 2026 •

edited

Loading