(aws-rds): Add support to `DatabaseCluster` to support `iam-db-auth` for masterUsername user.

[sbrinkerhoff]

Describe the feature

Using the aws cli one can create an AWS Aurora Serverless V2 Postgres cluster that utilizes IAM Authentication for the master-username.

# Create the cluster with IAM-only master auth
aws rds create-db-cluster \
  --db-cluster-identifier my-aurora-cluster \
  --engine aurora-postgresql \
  --region us-west-2 \
  --master-username postgres \
  --master-user-authentication-type iam-db-auth \
  --enable-iam-database-authentication

# Set scaling policy
aws rds modify-db-cluster \
  --db-cluster-identifier my-aurora-cluster \
  --serverless-v2-scaling-configuration MinCapacity=0.5,MaxCapacity=2 \
  --region us-west-2

# Add a Serverless v2 writer instance
aws rds create-db-instance \
  --db-instance-identifier my-aurora-cluster-writer \
  --db-cluster-identifier my-aurora-cluster \
  --engine aurora-postgresql \
  --db-instance-class db.serverless \
  --region us-west-2

This can be replicated using aws-cdk with the L1 constructs:

import { App, Stack, RemovalPolicy } from 'aws-cdk-lib';
import { CfnDBCluster, CfnDBInstance, CfnDBSubnetGroup } from 'aws-cdk-lib/aws-rds';
import { Vpc, SecurityGroup } from 'aws-cdk-lib/aws-ec2';

const app = new App();
const stack = new Stack(app, 'L1-IamAuth', {
  env: { account: 'YOUR-ACCOUNT-HERE', region: 'us-west-2' },
});

const vpc = Vpc.fromLookup(stack, 'Vpc', { vpcId: 'YOUR-VPC-HERE' });

const sg = new SecurityGroup(stack, 'DbSg', {
  vpc,
  description: 'Aurora cluster security group',
});

const subnetGroup = new CfnDBSubnetGroup(stack, 'SubnetGroup', {
  dbSubnetGroupDescription: 'Subnets for IAM auth repro cluster',
  subnetIds: vpc.privateSubnets.map(s => s.subnetId),
});

const cluster = new CfnDBCluster(stack, 'Cluster', {
  engine: 'aurora-postgresql',
  engineVersion: '17.5',
  masterUsername: 'postgres',
  masterUserAuthenticationType: 'iam-db-auth',
  enableIamDatabaseAuthentication: true,
  serverlessV2ScalingConfiguration: { minCapacity: 0.5, maxCapacity: 2 },
  dbSubnetGroupName: subnetGroup.ref,
  vpcSecurityGroupIds: [sg.securityGroupId],
  storageEncrypted: true,
});
cluster.applyRemovalPolicy(RemovalPolicy.DESTROY);

const writer = new CfnDBInstance(stack, 'Writer', {
  dbClusterIdentifier: cluster.ref,
  dbInstanceClass: 'db.serverless',
  engine: 'aurora-postgresql',
});

However there does not appear to be a functional way to use the L2 DatabaseCluster construct to achieve this same functionality. There is no masterUserAuthenticationType passed through in the construct.

const cluster = new DatabaseCluster(stack, 'DB', {
  engine: DatabaseClusterEngine.auroraPostgres({
    version: AuroraPostgresEngineVersion.VER_17_5,
  }),
  vpc,
  writer: ClusterInstance.serverlessV2('writer'),
  iamAuthentication: true,
  defaultDatabaseName: 'repro',
  removalPolicy: RemovalPolicy.DESTROY,
});

One can add a PropertyOverride:

const cfnCluster = cluster.node.defaultChild as CfnDBCluster;
cfnCluster.addPropertyOverride('MasterUserAuthenticationType', 'iam-db-auth');

However the MasterUserPassword is always set.

  "DB4924F778": {
   "Type": "AWS::RDS::DBCluster",
   "Properties": {
    "CopyTagsToSnapshot": true,
    "DBClusterParameterGroupName": "default.aurora-postgresql17",
    "DBSubnetGroupName": {
     "Ref": "DBSubnets7B70DA43"
    },
    "EnableIAMDatabaseAuthentication": true,
    "Engine": "aurora-postgresql",
    "EngineVersion": "17.5",
    "MasterUserAuthenticationType": "iam-db-auth",
    "MasterUserPassword": {
     "Fn::Join": [
      "",
      [
       "{{resolve:secretsmanager:",
       {
        "Ref": "DBSecretB8D1B379"
       },
       ":SecretString:password::}}"
      ]
     ]
    },

It is possible to override the masterUserPassword to enable creating an RDS Cluster with the L2 construct and IAM Master user authentication.

      const cfnCluster = this.databaseCluster.node.defaultChild as CfnDBCluster;
      const origDescriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(cfnCluster), 'cfnProperties');
      Object.defineProperty(cfnCluster, 'cfnProperties', {
        get() {
          const baseProps = origDescriptor?.get?.call(this) ?? {};
          delete baseProps.masterUserPassword;
          delete baseProps.manageMasterUserPassword;
          baseProps.masterUserAuthenticationType = 'iam-db-auth';
          return baseProps;
        },
        configurable: true,
      });

References

• https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-cluster.html
• https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBCluster.html
• https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_rds-readme.html

Use Case

Functional equivalency with the command line, and L1 construct should exist in the L2 construct.

Proposed Solution

Allow a prop that can configure the master database user to use IAM, and not set the MasterPassword value (which is always set right now, as renderCredentials will always set a password).

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

aws-cdk-lib@2.217.0

AWS CDK CLI version

2.1030.0

Environment details (OS name and version, etc.)

AL2023

[pahud]

Hi @sbrinkerhoff,

┌──────────────────────────────────────────────────────────┐
│ 🔴 Reported State                                        │
│ L2 DatabaseCluster always sets MasterUserPassword,       │
│ no way to use IAM-only auth for master user              │
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│ 🔍 Root Cause                                            │
│ renderCredentials() always generates a password;         │
│ masterUserAuthenticationType not passed to CfnDBCluster  │
│ cluster.ts L1495 + private/util.ts L90                   │
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│ 🟢 Suggested Fix                                         │
│ Add masterUserAuthenticationType prop + skip password    │
│ generation when IAM auth is selected                     │
└──────────────────────────────────────────────────────────┘

Thanks for the detailed write-up with CLI, L1, and L2 examples — this is a good catch. And thanks for already opening PR #37662 to address it!

I can confirm the gap from the source code. The L2 DatabaseCluster always calls renderCredentials() which guarantees a MasterUserPassword is set, and masterUserAuthenticationType is never passed through to the CfnDBCluster.

Your PR #37662 looks like a solid approach — adding MasterUserAuthenticationType enum, wiring it through DatabaseClusterBaseProps, and conditionally skipping password/secret generation when IAM auth is selected. The validation checks (no explicit secret/password with IAM, requiring iamAuthentication: true) are a nice touch.

A couple of things that might be worth considering for the PR:

• It appears DatabaseClusterFromSnapshot (cluster.ts L1679) has a similar credential rendering path — it may need the same treatment for consistency.
• The DatabaseInstance construct also supports masterUserAuthenticationType at the L1 level — might be worth a follow-up issue to track that separately.

Looking forward to seeing this land!

[sbrinkerhoff]

Good callout — I looked into this. DatabaseClusterFromSnapshot doesn't need the same treatment because:

1. masterUserAuthenticationType already flows through to the L1 via this.newCfnProps (since the prop was added to DatabaseClusterBaseProps, which both constructs share).

2. The credential path is fundamentally different. DatabaseClusterFromSnapshot uses renderSnapshotCredentials (not renderCredentials), and masterUserPassword is only set when the user explicitly provides snapshotCredentials with a password:

   masterUserPassword: credentials?.secret?.secretValueFromJson('password')?.unsafeUnwrap() 
     ?? credentials?.password?.unsafeUnwrap()

   When no snapshotCredentials are provided, this evaluates to undefined — no password is forced.

3. The snapshot construct doesn't set masterUsername at all (it's inherited from the snapshot), so there's no username/password generation to suppress.

So a user can already do:

new DatabaseClusterFromSnapshot(this, 'DB', {
  snapshotIdentifier: 'my-snapshot',
  engine: ...,
  iamAuthentication: true,
  masterUserAuthenticationType: MasterUserAuthenticationType.IAM,
  // no snapshotCredentials needed
});

and it works correctly — MasterUserAuthenticationType gets set on the L1, no password is emitted.

I added a unit test to confirm this behavior.

[sbrinkerhoff]

The DatabaseInstance construct also supports masterUserAuthenticationType at the L1 level — might be worth a follow-up issue to track that separately.

This is fine and works. The core issue of this PR was that when creating a cluster with IAM-Auth CDK (and Cloudformation) cannot set a password. The L1 construct can properly create an IAM-Auth cluster. The L2 construct almost can -- but it had no functional way to not set a password without a complex escape hatch.

The core of this PR is skipping the password generation logic in the L2 construct when IAM-Auth is provided. Secondarily it was adding the ability to accept the masterUserAuthenticationType as a prop rather than using addPropOverride.