AWS WAF SDK injection on CloudFront: eligibility, defaults, and missing tags

Check eligibility: CloudFront scope and three protections

Automatic SDK integration supplies client-side signals from the AWS WAF JavaScript SDK and is available only for a CloudFront-scope web ACL. The setting is not available for Regional web ACLs, including those used with Application Load Balancers. The ACL must contain at least one qualifying managed rule group: Bot Control with the targeted inspection level, account takeover prevention (ATP), or account creation fraud prevention (ACFP).

Bot Control at the common inspection level does not qualify. The Bot Control version does not affect targeted eligibility.

Setting a managed rule group action to Count does not remove eligibility, so you can insert SDK signals while evaluating the rule group. The integration itself does not make the Bot Control, ATP, or ACFP decision, and enabling it does not enforce those rules. AWS says there is no additional charge for automatic SDK integration; that does not make AWS WAF, managed rule groups, request processing, or other AWS services free overall.

Defaults depend on how the web ACL is created

When you create a new CloudFront web ACL in the AWS WAF console with a qualifying rule group, automatic SDK integration is enabled by default. Clear Enable automatic SDK integration before saving if you do not want it. Web ACLs created programmatically through the API, CLI, SDK, CDK, or CloudFormation start with the setting off.

ACLs created before this feature remain unchanged, and adding a qualifying rule group to an existing ACL does not turn integration on.

When you are ready to enable it, use the setting in a qualifying managed rule group in the console. In the API, the setting is AssociationConfig.ChallengeJavascriptSdkInjection.CLOUDFRONT on the web ACL. Keep at least one qualifying rule group while the setting is on.

If you remove the last qualifying group or change Bot Control from targeted to common, remove the integration setting in the same update or AWS WAF rejects the update. Omitting the setting from an UpdateWebACL request turns automatic integration off, even if it was enabled in the console.

Only eligible HTML responses receive the tag

CloudFront attempts insertion only in an origin response that AWS WAF allows through, has HTTP status 200, and has Content-Type text/html. Images, stylesheets, scripts, JSON, and other content types do not receive the tag. A custom error page returned with status 200 is handled like another page.

The origin object must be uncompressed and have a recognizable head element near the beginning: CloudFront scans only the first few kilobytes of the response body and places the tag after the opening head tag. Encodings that are not ASCII-compatible, such as UTF-16 or UTF-32, are not modified.

The scan is a fast byte scan, not a full HTML parse. An earlier comment or invalid head can cause the tag to be placed in the wrong location, where the browser will not run it. Compressed origin objects, including HTML stored in S3 with Content-Encoding: gzip, are not modified.

CloudFront requests every object that AWS WAF allows from the origin uncompressed, not just HTML. To keep serving compressed objects to viewers, enable the applicable compression setting in the CloudFront cache behavior.

The setting covers the web ACL and changes Range requests

You cannot enable or disable insertion for individual URL paths with this setting. It applies to eligible origin responses allowed under the web ACL whether or not a qualifying rule group evaluated the request; a rule-group scope-down statement or an earlier Allow rule does not prevent insertion. To exclude specific pages, have the origin send Cache-Control: no-transform on those responses.

Other Cache-Control directives, including no-store and private, do not opt out.

With the setting on, CloudFront removes Range and If-Range from every request AWS WAF allows and returns the complete object with HTTP 200, regardless of content type. This affects video, audio, segmented downloads, and other range-request clients, and increases the data transferred for those requests. Check compression, caching, and range behavior with your applications.

After insertion, Content-Length is updated or may be omitted for chunked responses; ETag becomes a weak validator different from the origin value. Body-integrity headers such as Content-MD5, Digest, Content-Digest, and Repr-Digest are not recalculated.

Check CSP and application API token flows

A Content-Security-Policy response header or meta policy must allow the SDK to load and make its required requests. The AWS CSP guide lists connect-src, script-src, and script-src-elem among the relevant directives; allow https://*.awswaf.com in the directives that your policy uses. Automatic insertion does not support strict-dynamic policies that rely on nonces or hashes: the inserted tag has no page nonce, and browsers ignore the host allowlist.

Keep the strict policy and add the script manually with the required nonce using the documented JavaScript integration; do not weaken CSP to make automatic insertion work.

The inserted SDK obtains and refreshes a token after the page loads, but requests sent before the first token exists do not carry one. If a single-page application relies on the SDK to attach tokens to its own API calls, keep its existing manual integration or use the documented API integration. Automatic integration inserts only the AWS WAF SDK tag; it does not insert the CAPTCHA JavaScript API or mobile SDKs, and it does not attach tokens to arbitrary application API calls for you.

Missing tags can result from caches or architecture exceptions

Origin Shield is unsupported, so responses from an origin using it may not receive the tag consistently; cached copies without the tag can continue to be served. Cache behaviors with Lambda@Edge on origin-request or origin-response events are unsupported, while viewer events do not affect insertion into origin responses. For distributions using CloudFront embedded POPs, uncached responses served by those POPs are not modified.

At high origin request rates, some uncached requests, such as POST requests or behaviors with a maximum TTL of zero, may also return without insertion. Integrate the SDK directly on pages that must always run it; manual and automatic integration can coexist.

CloudFront-cached HTML keeps the version stored before you enabled the setting, and a cached copy can still contain the tag after you disable it until it expires or is evicted. Browsers and downstream caches also retain old copies. A conditional request that returns 304 leaves the viewer with its previously stored page.

Invalidating CloudFront does not clear downstream caches. To make an update take effect right away, invalidate the relevant HTML paths and account for browser caching.

Verify the tag, SDK runtime, and rule results separately

AWS WAF does not provide a metric or log field that records whether each response received the inserted tag. To check for the tag, view page source in a private browsing window or after clearing the browser cache and cookies; if HTML is cached, CloudFront may still serve an older copy. To check whether the SDK runs, verify that the browser receives an aws-waf-token cookie.

A tag in page source does not show that CSP allowed it to run, and a token alone does not prove that a particular managed rule is effective.

If insertion fails, CloudFront returns the origin response body unchanged. This fail-open behavior does not block the page. Requests blocked by AWS WAF, or replaced by a Challenge or CAPTCHA response, do not get an origin page with the SDK tag; responses generated by CloudFront Functions are not modified either.

Before blocking requests for a missing token, set the relevant rules to Count and review the results, since legitimate users can lack a token when their page did not run the SDK.