@aws/nx-plugin 1.0.0-rc.76 → 1.0.0-rc.78

package/src/ts/react-website/app/__snapshots__/generator.spec.ts.snap

@@ -164,6 +164,41 @@ variable "acm_certificate_arn" {
   default     = null
 }
 
+variable "enable_waf" {
+  description = "Whether to protect the CloudFront distribution with an AWS WAF Web ACL."
+  type        = bool
+  default     = true
+}
+
+variable "encryption" {
+  description = "Server-side encryption for the website and distribution log buckets. One of KMS or S3_MANAGED."
+  type        = string
+  default     = "KMS"
+
+  validation {
+    condition     = contains(["KMS", "S3_MANAGED"], var.encryption)
+    error_message = "encryption must be one of KMS or S3_MANAGED."
+  }
+}
+
+variable "kms_key_arn" {
+  description = "ARN of an existing KMS key used to encrypt the website and distribution log buckets when encryption is KMS. When not provided and create_kms_key is true, a new key is created. Note that a customer-supplied key must already grant the CloudWatch Logs, S3 and CloudFront service principals the necessary permissions in its own key policy."
+  type        = string
+  default     = null
+}
+
+variable "create_kms_key" {
+  description = "Whether to create a KMS key for the website. Only applies when encryption is KMS. Set to false when supplying kms_key_arn."
+  type        = bool
+  default     = true
+}
+
+variable "enable_key_rotation" {
+  description = "Whether the automatically created KMS key has rotation enabled. Only applies when encryption is KMS and create_kms_key is true."
+  type        = bool
+  default     = true
+}
+
 # Content-Security-Policy enforced on all responses. Restricts scripts and
 # framing to mitigate XSS and clickjacking, while permitting HTTPS/WSS calls
 # (connect-src) to AWS service endpoints such as API Gateway, Cognito and
@@ -175,6 +210,13 @@ locals {
   # Delivery source/destination names have a 60 character maximum. Truncate the
   # website name so the longest delivery name stays within the limit.
   access_logs_name_prefix = substr(lower(var.website_name), 0, 16)
+
+  create_website_key = var.encryption == "KMS" && var.create_kms_key
+  website_kms_key_arn = (
+    var.encryption != "KMS" ? null :
+    local.create_website_key ? aws_kms_key.website_key[0].arn :
+    var.kms_key_arn
+  )
 }
 
 
@@ -185,9 +227,11 @@ data "aws_region" "current" {}
 
 # KMS Key for encryption
 resource "aws_kms_key" "website_key" {
+  count = local.create_website_key ? 1 : 0
+
   description             = "KMS key for \${var.website_name} website encryption"
   deletion_window_in_days = 7
-  enable_key_rotation     = true
+  enable_key_rotation     = var.enable_key_rotation
 
   policy = jsonencode({
     Version = "2012-10-17"
@@ -260,8 +304,10 @@ resource "aws_kms_key" "website_key" {
 }
 
 resource "aws_kms_alias" "website_key_alias" {
+  count = local.create_website_key ? 1 : 0
+
   name          = "alias/\${lower(var.website_name)}-website-key-\${random_id.unique_suffix.hex}"
-  target_key_id = aws_kms_key.website_key.key_id
+  target_key_id = aws_kms_key.website_key[0].key_id
 }
 
 # CloudWatch log group receiving S3 server access logs for the website and
@@ -269,7 +315,7 @@ resource "aws_kms_alias" "website_key_alias" {
 resource "aws_cloudwatch_log_group" "access_logs" {
   name              = "/aws/s3/\${lower(var.website_name)}-access-logs-\${random_id.bucket_suffix.hex}"
   retention_in_days = 365
-  kms_key_id        = aws_kms_key.website_key.arn
+  kms_key_id        = local.website_kms_key_arn
 }
 
 resource "random_id" "unique_suffix" {
@@ -306,8 +352,8 @@ resource "aws_s3_bucket_server_side_encryption_configuration" "website_encryptio
 
   rule {
     apply_server_side_encryption_by_default {
-      kms_master_key_id = aws_kms_key.website_key.arn
-      sse_algorithm     = "aws:kms"
+      kms_master_key_id = var.encryption == "KMS" ? local.website_kms_key_arn : null
+      sse_algorithm     = var.encryption == "KMS" ? "aws:kms" : "AES256"
     }
   }
 }
@@ -371,8 +417,8 @@ resource "aws_s3_bucket_server_side_encryption_configuration" "distribution_logs
 
   rule {
     apply_server_side_encryption_by_default {
-      kms_master_key_id = aws_kms_key.website_key.arn
-      sse_algorithm     = "aws:kms"
+      kms_master_key_id = var.encryption == "KMS" ? local.website_kms_key_arn : null
+      sse_algorithm     = var.encryption == "KMS" ? "aws:kms" : "AES256"
     }
   }
 }
@@ -442,6 +488,8 @@ resource "aws_s3_bucket_policy" "distribution_logs_ssl_policy" {
 
 # WAF Web ACL (must be in us-east-1 for CloudFront)
 resource "aws_wafv2_web_acl" "cloudfront_waf" {
+  count = var.enable_waf ? 1 : 0
+
   #checkov:skip=CKV2_AWS_31:WAF logging disabled
   provider = aws.us_east_1
   name     = "\${lower(var.website_name)}-cloudfront-waf-\${random_id.unique_suffix.hex}"
@@ -566,7 +614,7 @@ resource "aws_cloudfront_distribution" "website" {
   enabled             = true
   is_ipv6_enabled     = true
   default_root_object = "index.html"
-  web_acl_id          = aws_wafv2_web_acl.cloudfront_waf.arn
+  web_acl_id          = var.enable_waf ? aws_wafv2_web_acl.cloudfront_waf[0].arn : null
   aliases             = var.custom_domain_names
 
   logging_config {
@@ -624,12 +672,6 @@ resource "aws_cloudfront_distribution" "website" {
     Name = "\${lower(var.website_name)}-distribution-\${random_id.unique_suffix.hex}"
   }
 
-  lifecycle {
-    replace_triggered_by = [
-      aws_wafv2_web_acl.cloudfront_waf
-    ]
-  }
-
   # CloudFront validates access to the distribution logs bucket when it
   # creates the distribution.
   depends_on = [
@@ -902,7 +944,7 @@ output "cloudfront_domain_name" {
 
 output "waf_web_acl_arn" {
   description = "ARN of the WAF Web ACL"
-  value       = aws_wafv2_web_acl.cloudfront_waf.arn
+  value       = var.enable_waf ? aws_wafv2_web_acl.cloudfront_waf[0].arn : null
 }",
   "test-app.tf": "terraform {
   required_providers {
@@ -914,6 +956,53 @@ output "waf_web_acl_arn" {
   }
 }
 
+variable "custom_domain_names" {
+  description = "Custom domain names (aliases) for the CloudFront distribution. Requires acm_certificate_arn."
+  type        = list(string)
+  default     = []
+}
+
+variable "acm_certificate_arn" {
+  description = "ARN of an ACM certificate (in us-east-1) for the custom domain names. When set, viewers are required to use TLS 1.2 or later."
+  type        = string
+  default     = null
+}
+
+variable "enable_waf" {
+  description = "Whether to protect the CloudFront distribution with an AWS WAF Web ACL."
+  type        = bool
+  default     = true
+}
+
+variable "encryption" {
+  description = "Server-side encryption for the website and distribution log buckets. One of KMS or S3_MANAGED."
+  type        = string
+  default     = "KMS"
+
+  validation {
+    condition     = contains(["KMS", "S3_MANAGED"], var.encryption)
+    error_message = "encryption must be one of KMS or S3_MANAGED."
+  }
+}
+
+variable "kms_key_arn" {
+  description = "ARN of an existing KMS key used to encrypt the website and distribution log buckets when encryption is KMS. When not provided and create_kms_key is true, a new key is created. Note that a customer-supplied key must already grant the CloudWatch Logs, S3 and CloudFront service principals the necessary permissions in its own key policy."
+  type        = string
+  default     = null
+}
+
+variable "create_kms_key" {
+  description = "Whether to create a KMS key for the website. Only applies when encryption is KMS. Set to false when supplying kms_key_arn."
+  type        = bool
+  default     = true
+}
+
+variable "enable_key_rotation" {
+  description = "Whether the automatically created KMS key has rotation enabled. Only applies when encryption is KMS and create_kms_key is true."
+  type        = bool
+  default     = true
+}
+
 # Static website module configured for the web package
 module "static_website" {
   source = "../../../core/static-website"
@@ -921,6 +1010,14 @@ module "static_website" {
   website_name      = "test-app"
   website_file_path = "\${path.module}/../../../../../../../dist/test-app/bundle"
 
+  custom_domain_names = var.custom_domain_names
+  acm_certificate_arn = var.acm_certificate_arn
+  enable_waf          = var.enable_waf
+  encryption          = var.encryption
+  kms_key_arn         = var.kms_key_arn
+  create_kms_key      = var.create_kms_key
+  enable_key_rotation = var.enable_key_rotation
+
   providers = {
     aws.us_east_1 = aws.us_east_1
   }
@@ -1299,11 +1396,17 @@ exports[`react-website generator > Tanstack router integration > should generate
 exports[`react-website generator > Tanstack router integration > should generate website with no router correctly > packages/common/constructs/src/app/static-websites/test-app.ts 1`] = `
 "import * as url from 'url';
 import { Construct } from 'constructs';
-import { StaticWebsite } from '../../core/index.js';
+import { StaticWebsite, StaticWebsiteProps } from '../../core/index.js';
+
+export type TestAppProps = Omit<
+  StaticWebsiteProps,
+  'websiteName' | 'websiteFilePath'
+>;
 
 export class TestApp extends StaticWebsite {
-  constructor(scope: Construct, id: string) {
+  constructor(scope: Construct, id: string, props?: TestAppProps) {
     super(scope, id, {
+      ...props,
       websiteName: 'TestApp',
       websiteFilePath: url.fileURLToPath(
         new URL('../../../../../../dist/test-app/bundle', import.meta.url),
@@ -1641,7 +1744,7 @@ import {
 } from 'aws-cdk-lib/aws-s3-deployment';
 import { Construct } from 'constructs';
 import { RuntimeConfig } from './runtime-config.js';
-import { Key } from 'aws-cdk-lib/aws-kms';
+import { IKey, Key } from 'aws-cdk-lib/aws-kms';
 import {
   CfnDelivery,
   CfnDeliveryDestination,
@@ -1684,6 +1787,33 @@ export interface StaticWebsiteProps {
    * When provided, viewers are required to use TLS 1.2 or later.
    */
   readonly certificate?: ICertificate;
+  /**
+   * Whether to protect the CloudFront distribution with an AWS WAF Web ACL.
+   *
+   * @default true
+   */
+  readonly enableWaf?: boolean;
+  /**
+   * Server-side encryption for the website and distribution log buckets.
+   *
+   * @default BucketEncryption.KMS
+   */
+  readonly encryption?: BucketEncryption;
+  /**
+   * KMS key used to encrypt the website and distribution log buckets. Only used when \`encryption\` is
+   * \`BucketEncryption.KMS\`. When not provided, a new key is created. Note that a key imported via
+   * \`Key.fromKeyArn\` must already grant the CloudWatch Logs, S3 and CloudFront service principals the
+   * necessary permissions in its own key policy - \`addToResourcePolicy\` is a no-op on an imported key,
+   * so this construct cannot grant them on your behalf.
+   */
+  readonly encryptionKey?: IKey;
+  /**
+   * Whether the automatically created KMS key has rotation enabled. Only applies when \`encryption\` is
+   * \`BucketEncryption.KMS\` and no \`encryptionKey\` is supplied.
+   *
+   * @default true
+   */
+  readonly enableKeyRotation?: boolean;
 }
 
 /**
@@ -1707,17 +1837,22 @@ export class StaticWebsite extends Construct {
       websiteName,
       domainNames,
       certificate,
+      enableWaf = true,
+      encryption = BucketEncryption.KMS,
+      encryptionKey,
+      enableKeyRotation = true,
     }: StaticWebsiteProps,
   ) {
     super(scope, id);
 
-    const websiteKey = new Key(this, 'WebsiteKey', {
-      enableKeyRotation: true,
-    });
+    const websiteKey: IKey | undefined =
+      encryption === BucketEncryption.KMS
+        ? (encryptionKey ?? new Key(this, 'WebsiteKey', { enableKeyRotation }))
+        : undefined;
 
     // Allow CloudWatch Logs to use the website key for server access log delivery.
     const stack = Stack.of(this);
-    websiteKey.addToResourcePolicy(
+    websiteKey?.addToResourcePolicy(
       new PolicyStatement({
         effect: Effect.ALLOW,
         principals: [
@@ -1751,7 +1886,7 @@ export class StaticWebsite extends Construct {
       enforceSSL: true,
       autoDeleteObjects: true,
       removalPolicy: RemovalPolicy.DESTROY,
-      encryption: BucketEncryption.KMS,
+      encryption,
       encryptionKey: websiteKey,
       objectOwnership: ObjectOwnership.BUCKET_OWNER_ENFORCED,
       publicReadAccess: false,
@@ -1768,7 +1903,7 @@ export class StaticWebsite extends Construct {
       accessLogs,
     );
     // Web ACL
-    const wafStack = new CloudfrontWebAcl(this, 'waf');
+    const wafStack = enableWaf ? new CloudfrontWebAcl(this, 'waf') : undefined;
 
     // Bucket holding CloudFront standard access logs. CloudFront delivers its
     // own logs to S3 only, so this bucket is retained; its S3 server access
@@ -1777,7 +1912,7 @@ export class StaticWebsite extends Construct {
       enforceSSL: true,
       autoDeleteObjects: true,
       removalPolicy: RemovalPolicy.DESTROY,
-      encryption: BucketEncryption.KMS,
+      encryption,
       encryptionKey: websiteKey,
       objectOwnership: ObjectOwnership.BUCKET_OWNER_PREFERRED,
       publicReadAccess: false,
@@ -1830,7 +1965,7 @@ export class StaticWebsite extends Construct {
       this,
       'CloudfrontDistribution',
       {
-        webAclId: wafStack.wafArn,
+        webAclId: wafStack?.wafArn,
         enableLogging: true,
         logBucket: logBucket,
         ...(certificate
@@ -3124,11 +3259,17 @@ exports[`react-website generator > Tanstack router integration > should generate
 exports[`react-website generator > Tanstack router integration > should generate website with router correctly > packages/common/constructs/src/app/static-websites/test-app.ts 1`] = `
 "import * as url from 'url';
 import { Construct } from 'constructs';
-import { StaticWebsite } from '../../core/index.js';
+import { StaticWebsite, StaticWebsiteProps } from '../../core/index.js';
+
+export type TestAppProps = Omit<
+  StaticWebsiteProps,
+  'websiteName' | 'websiteFilePath'
+>;
 
 export class TestApp extends StaticWebsite {
-  constructor(scope: Construct, id: string) {
+  constructor(scope: Construct, id: string, props?: TestAppProps) {
     super(scope, id, {
+      ...props,
       websiteName: 'TestApp',
       websiteFilePath: url.fileURLToPath(
         new URL('../../../../../../dist/test-app/bundle', import.meta.url),
@@ -3466,7 +3607,7 @@ import {
 } from 'aws-cdk-lib/aws-s3-deployment';
 import { Construct } from 'constructs';
 import { RuntimeConfig } from './runtime-config.js';
-import { Key } from 'aws-cdk-lib/aws-kms';
+import { IKey, Key } from 'aws-cdk-lib/aws-kms';
 import {
   CfnDelivery,
   CfnDeliveryDestination,
@@ -3509,6 +3650,33 @@ export interface StaticWebsiteProps {
    * When provided, viewers are required to use TLS 1.2 or later.
    */
   readonly certificate?: ICertificate;
+  /**
+   * Whether to protect the CloudFront distribution with an AWS WAF Web ACL.
+   *
+   * @default true
+   */
+  readonly enableWaf?: boolean;
+  /**
+   * Server-side encryption for the website and distribution log buckets.
+   *
+   * @default BucketEncryption.KMS
+   */
+  readonly encryption?: BucketEncryption;
+  /**
+   * KMS key used to encrypt the website and distribution log buckets. Only used when \`encryption\` is
+   * \`BucketEncryption.KMS\`. When not provided, a new key is created. Note that a key imported via
+   * \`Key.fromKeyArn\` must already grant the CloudWatch Logs, S3 and CloudFront service principals the
+   * necessary permissions in its own key policy - \`addToResourcePolicy\` is a no-op on an imported key,
+   * so this construct cannot grant them on your behalf.
+   */
+  readonly encryptionKey?: IKey;
+  /**
+   * Whether the automatically created KMS key has rotation enabled. Only applies when \`encryption\` is
+   * \`BucketEncryption.KMS\` and no \`encryptionKey\` is supplied.
+   *
+   * @default true
+   */
+  readonly enableKeyRotation?: boolean;
 }
 
 /**
@@ -3532,17 +3700,22 @@ export class StaticWebsite extends Construct {
       websiteName,
       domainNames,
       certificate,
+      enableWaf = true,
+      encryption = BucketEncryption.KMS,
+      encryptionKey,
+      enableKeyRotation = true,
     }: StaticWebsiteProps,
   ) {
     super(scope, id);
 
-    const websiteKey = new Key(this, 'WebsiteKey', {
-      enableKeyRotation: true,
-    });
+    const websiteKey: IKey | undefined =
+      encryption === BucketEncryption.KMS
+        ? (encryptionKey ?? new Key(this, 'WebsiteKey', { enableKeyRotation }))
+        : undefined;
 
     // Allow CloudWatch Logs to use the website key for server access log delivery.
     const stack = Stack.of(this);
-    websiteKey.addToResourcePolicy(
+    websiteKey?.addToResourcePolicy(
       new PolicyStatement({
         effect: Effect.ALLOW,
         principals: [
@@ -3576,7 +3749,7 @@ export class StaticWebsite extends Construct {
       enforceSSL: true,
       autoDeleteObjects: true,
       removalPolicy: RemovalPolicy.DESTROY,
-      encryption: BucketEncryption.KMS,
+      encryption,
       encryptionKey: websiteKey,
       objectOwnership: ObjectOwnership.BUCKET_OWNER_ENFORCED,
       publicReadAccess: false,
@@ -3593,7 +3766,7 @@ export class StaticWebsite extends Construct {
       accessLogs,
     );
     // Web ACL
-    const wafStack = new CloudfrontWebAcl(this, 'waf');
+    const wafStack = enableWaf ? new CloudfrontWebAcl(this, 'waf') : undefined;
 
     // Bucket holding CloudFront standard access logs. CloudFront delivers its
     // own logs to S3 only, so this bucket is retained; its S3 server access
@@ -3602,7 +3775,7 @@ export class StaticWebsite extends Construct {
       enforceSSL: true,
       autoDeleteObjects: true,
       removalPolicy: RemovalPolicy.DESTROY,
-      encryption: BucketEncryption.KMS,
+      encryption,
       encryptionKey: websiteKey,
       objectOwnership: ObjectOwnership.BUCKET_OWNER_PREFERRED,
       publicReadAccess: false,
@@ -3655,7 +3828,7 @@ export class StaticWebsite extends Construct {
       this,
       'CloudfrontDistribution',
       {
-        webAclId: wafStack.wafArn,
+        webAclId: wafStack?.wafArn,
         enableLogging: true,
         logBucket: logBucket,
         ...(certificate
@@ -5151,7 +5324,7 @@ import {
 } from 'aws-cdk-lib/aws-s3-deployment';
 import { Construct } from 'constructs';
 import { RuntimeConfig } from './runtime-config.js';
-import { Key } from 'aws-cdk-lib/aws-kms';
+import { IKey, Key } from 'aws-cdk-lib/aws-kms';
 import {
   CfnDelivery,
   CfnDeliveryDestination,
@@ -5194,6 +5367,33 @@ export interface StaticWebsiteProps {
    * When provided, viewers are required to use TLS 1.2 or later.
    */
   readonly certificate?: ICertificate;
+  /**
+   * Whether to protect the CloudFront distribution with an AWS WAF Web ACL.
+   *
+   * @default true
+   */
+  readonly enableWaf?: boolean;
+  /**
+   * Server-side encryption for the website and distribution log buckets.
+   *
+   * @default BucketEncryption.KMS
+   */
+  readonly encryption?: BucketEncryption;
+  /**
+   * KMS key used to encrypt the website and distribution log buckets. Only used when \`encryption\` is
+   * \`BucketEncryption.KMS\`. When not provided, a new key is created. Note that a key imported via
+   * \`Key.fromKeyArn\` must already grant the CloudWatch Logs, S3 and CloudFront service principals the
+   * necessary permissions in its own key policy - \`addToResourcePolicy\` is a no-op on an imported key,
+   * so this construct cannot grant them on your behalf.
+   */
+  readonly encryptionKey?: IKey;
+  /**
+   * Whether the automatically created KMS key has rotation enabled. Only applies when \`encryption\` is
+   * \`BucketEncryption.KMS\` and no \`encryptionKey\` is supplied.
+   *
+   * @default true
+   */
+  readonly enableKeyRotation?: boolean;
 }
 
 /**
@@ -5217,17 +5417,22 @@ export class StaticWebsite extends Construct {
       websiteName,
       domainNames,
       certificate,
+      enableWaf = true,
+      encryption = BucketEncryption.KMS,
+      encryptionKey,
+      enableKeyRotation = true,
     }: StaticWebsiteProps,
   ) {
     super(scope, id);
 
-    const websiteKey = new Key(this, 'WebsiteKey', {
-      enableKeyRotation: true,
-    });
+    const websiteKey: IKey | undefined =
+      encryption === BucketEncryption.KMS
+        ? (encryptionKey ?? new Key(this, 'WebsiteKey', { enableKeyRotation }))
+        : undefined;
 
     // Allow CloudWatch Logs to use the website key for server access log delivery.
     const stack = Stack.of(this);
-    websiteKey.addToResourcePolicy(
+    websiteKey?.addToResourcePolicy(
       new PolicyStatement({
         effect: Effect.ALLOW,
         principals: [
@@ -5261,7 +5466,7 @@ export class StaticWebsite extends Construct {
       enforceSSL: true,
       autoDeleteObjects: true,
       removalPolicy: RemovalPolicy.DESTROY,
-      encryption: BucketEncryption.KMS,
+      encryption,
       encryptionKey: websiteKey,
       objectOwnership: ObjectOwnership.BUCKET_OWNER_ENFORCED,
       publicReadAccess: false,
@@ -5278,7 +5483,7 @@ export class StaticWebsite extends Construct {
       accessLogs,
     );
     // Web ACL
-    const wafStack = new CloudfrontWebAcl(this, 'waf');
+    const wafStack = enableWaf ? new CloudfrontWebAcl(this, 'waf') : undefined;
 
     // Bucket holding CloudFront standard access logs. CloudFront delivers its
     // own logs to S3 only, so this bucket is retained; its S3 server access
@@ -5287,7 +5492,7 @@ export class StaticWebsite extends Construct {
       enforceSSL: true,
       autoDeleteObjects: true,
       removalPolicy: RemovalPolicy.DESTROY,
-      encryption: BucketEncryption.KMS,
+      encryption,
       encryptionKey: websiteKey,
       objectOwnership: ObjectOwnership.BUCKET_OWNER_PREFERRED,
       publicReadAccess: false,
@@ -5340,7 +5545,7 @@ export class StaticWebsite extends Construct {
       this,
       'CloudfrontDistribution',
       {
-        webAclId: wafStack.wafArn,
+        webAclId: wafStack?.wafArn,
         enableLogging: true,
         logBucket: logBucket,
         ...(certificate
@@ -5539,11 +5744,17 @@ export class CloudfrontWebAcl extends Stack {
 exports[`react-website generator > should generate shared constructs > test-app.ts 1`] = `
 "import * as url from 'url';
 import { Construct } from 'constructs';
-import { StaticWebsite } from '../../core/index.js';
+import { StaticWebsite, StaticWebsiteProps } from '../../core/index.js';
+
+export type TestAppProps = Omit<
+  StaticWebsiteProps,
+  'websiteName' | 'websiteFilePath'
+>;
 
 export class TestApp extends StaticWebsite {
-  constructor(scope: Construct, id: string) {
+  constructor(scope: Construct, id: string, props?: TestAppProps) {
     super(scope, id, {
+      ...props,
       websiteName: 'TestApp',
       websiteFilePath: url.fileURLToPath(
         new URL('../../../../../../dist/test-app/bundle', import.meta.url),

package/src/ts/react-website/cognito-auth/__snapshots__/generator.spec.ts.snap

@@ -105,6 +105,7 @@ import {
   FeaturePlan,
   ManagedLoginVersion,
   Mfa,
+  type MfaSecondFactor,
   OAuthScope,
   StandardThreatProtectionMode,
   UserPool,
@@ -137,6 +138,20 @@ export interface UserIdentityProps {
    * @default true
    */
   readonly enableWaf?: boolean;
+
+  /**
+   * Whether users must configure MFA, may optionally configure MFA, or cannot use MFA at all.
+   *
+   * @default Mfa.REQUIRED
+   */
+  readonly mfa?: Mfa;
+
+  /**
+   * The MFA methods available to users when MFA is not off.
+   *
+   * @default { sms: true, otp: true }
+   */
+  readonly mfaSecondFactor?: MfaSecondFactor;
 }
 
 /**
@@ -155,12 +170,22 @@ export class UserIdentity extends Construct {
   constructor(
     scope: Construct,
     id: string,
-    { enableWaf = true }: UserIdentityProps = {},
+    {
+      enableWaf = true,
+      mfa = Mfa.REQUIRED,
+      mfaSecondFactor = { sms: true, otp: true },
+    }: UserIdentityProps = {},
   ) {
     super(scope, id);
 
+    if (mfa === Mfa.REQUIRED && !mfaSecondFactor.sms && !mfaSecondFactor.otp) {
+      throw new Error(
+        'UserIdentity: mfa is REQUIRED but mfaSecondFactor has no methods enabled (sms and otp are both false)',
+      );
+    }
+
     this.region = Stack.of(this).region;
-    this.userPool = this.createUserPool();
+    this.userPool = this.createUserPool(mfa, mfaSecondFactor);
 
     if (enableWaf) {
       this.webAcl = this.createWebAcl(
@@ -208,7 +233,12 @@ export class UserIdentity extends Construct {
     });
   }
 
-  private createUserPool = () => {
+  private createUserPool = (mfa: Mfa, mfaSecondFactor: MfaSecondFactor) => {
+    // Cognito rejects SmsConfiguration (emitted whenever phone is auto-verified) unless SMS is
+    // also an enabled MFA method, for any non-OFF MfaConfiguration. So phone verification via SMS
+    // can only be offered when SMS is actually usable as a second factor.
+    const phoneVerificationEnabled = mfa === Mfa.OFF || mfaSecondFactor.sms;
+
     const userPool = new UserPool(this, 'UserPool', {
       deletionProtection: true,
       passwordPolicy: {
@@ -219,11 +249,11 @@ export class UserIdentity extends Construct {
         requireSymbols: true,
         tempPasswordValidity: Duration.days(3),
       },
-      mfa: Mfa.REQUIRED,
+      mfa,
       featurePlan: FeaturePlan.PLUS,
       // Audit-only logs threat assessments without blocking sign-in. Switch to FULL_FUNCTION to enforce automatic responses.
       standardThreatProtectionMode: StandardThreatProtectionMode.AUDIT_ONLY,
-      mfaSecondFactor: { sms: true, otp: true },
+      mfaSecondFactor,
       signInCaseSensitive: false,
       signInAliases: { username: true, email: true },
       accountRecovery: AccountRecovery.EMAIL_ONLY,
@@ -236,11 +266,11 @@ export class UserIdentity extends Construct {
       },
       autoVerify: {
         email: true,
-        phone: true,
+        phone: phoneVerificationEnabled,
       },
       keepOriginal: {
         email: true,
-        phone: true,
+        phone: phoneVerificationEnabled,
       },
     });
     // Retain the SMS role alongside the pool so the pool can still be updated and deleted manually