aws-cloudfront: webAclId property in Distribution requires WebACL ARN, not ID, for WAFv2

[unphydra]

Describe the bug

Summary:

The webAclId property in the CDK cloudfront.Distribution construct is documented to accept an ID, but when associating an AWS WAFv2 Web ACL, it actually requires the full Amazon Resource Name (ARN) of the Web ACL to succeed. Passing only the ID results in a CloudFormation deployment failure with a misleading error.

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

No response

Expected Behavior

Expected Behavior / Suggestions

1. Ideal Solution: Since the property is named webAclId, the CDK construct should internally handle whether an ID or an ARN is provided, mapping it to the correct format required by the underlying CloudFormation resource (which expects the ARN for WAFv2).
2. Alternative Solution (Documentation Fix): At minimum, the documentation for the webAclId property should be updated to clearly state that for WAFv2, the ARN must be provided.

Current Behavior

Issue

When attempting to associate an AWS WAFv2 Web ACL with a cloudfront.Distribution using the webAclId property, passing only the Web ACL ID (e.g., a1b2c3d4-5678-90ab-cdef-EXAMPLE11111) leads to a deployment failure with the following error:

Resource handler returned message: "Invalid request provided: Web ACL is not accessible by the requester." (RequestToken: ..., HandlerErrorCode: InvalidRequest)

The error is misleading as it suggests an IAM issue, but the underlying CloudFormation resource expects the full ARN for WAFv2 Web ACLs.

Reproduction Steps

Reproduction Steps

1. Create an AWS WAFv2 Web ACL in the N. Virginia (us-east-1) region with scope CLOUDFRONT.
2. In a CDK stack, create a cloudfront.Distribution.
3. Attempt to pass only the Web ACL ID (not the full ARN) to the webAclId property of the Distribution construct.
4. Deploy the stack using cdk deploy.

Possible Solution

Workaround

The deployment succeeds when the full ARN of the WAFv2 Web ACL is provided instead of the ID:

// Example of a successful deployment using ARN
const webAclArn = 'arn:aws:wafv2:us-east-1:123456789012:global/webacl/MyWebACL/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111';

new cloudfront.Distribution(this, 'MyDistribution', {
  // ... other properties
  webAclId: webAclArn, // Passing the ARN works
});

Additional Information/Context

What did I use to get this result?

• CDK CLI Version: (Please insert your CDK version, e.g., 2.1033.0,)
• AWS CDK Packages Used: aws-cdk-lib/aws-cloudfront, aws-cdk-lib/aws-wafv2
• Language (A specific version of the language if applicable): TypeScript/Node.js

AWS CDK Library version (aws-cdk-lib)

2.231.0

AWS CDK CLI version

2.1033.0

Node.js Version

22.17.1

OS

mac

Language

TypeScript

Language Version

5.9.3

Other information

No response

[pahud]

Hi

From what I read in the source and doc, the property name webAclId suggests it accepts a Web ACL ID, but for WAFv2 Web ACLs, it actually requires the full ARN. This naming comes from the underlying CloudFormation property which accepts either format depending on whether you're using WAF Classic (ID) or WAFv2 (ARN). The current implementation in the Distribution class passes the value directly to CloudFormation without transformation.

https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.Distribution.html#webaclid

aws-cdk/packages/aws-cdk-lib/aws-cloudfront/lib/web-distribution.ts

Lines 669 to 682 in 0945692

	/**
	* Unique identifier that specifies the AWS WAF web ACL to associate with this CloudFront distribution.
	*
	* To specify a web ACL created using the latest version of AWS WAF, use the ACL ARN, for example
	* `arn:aws:wafv2:us-east-1:123456789012:global/webacl/ExampleWebACL/473e64fd-f30b-4765-81a0-62ad96dd167a`.
	*
	* To specify a web ACL created using AWS WAF Classic, use the ACL ID, for example `473e64fd-f30b-4765-81a0-62ad96dd167a`.
	*
	* @see https://docs.aws.amazon.com/waf/latest/developerguide/what-is-aws-waf.html
	* @see https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateDistribution.html#API_CreateDistribution_RequestParameters.
	*
	* @default - No AWS Web Application Firewall web access control list (web ACL).
	*/
	readonly webACLId?: string;

Why the Error is Misleading:
When you pass just the ID for a WAFv2 Web ACL, CloudFormation interprets it as a WAF Classic ID and fails to find it, resulting in the "Web ACL is not accessible" error which incorrectly suggests an IAM issue.

Potential Solutions:

1. Add intelligent detection and ARN construction for WAFv2 IDs
2. Improve validation to provide clearer error messages when ID format is detected for WAFv2
3. Consider deprecating webAclId in favor of a more accurately named property

The README documentation does mention this requirement in the "Attaching WAF Web Acls" section, but the property name creates a strong expectation that contradicts the documentation.

Please let me know if we can refine it further to ensure clarity and accuracy.

[unphydra]

Thanks for the clarification; this looks good.
I apologise, I missed the point in the README documentation that the ID specifically pertains to WAF Classic.