Recovering The Real Client Ip Behind A CDN

Does not cover the rules themselves in depth (see the rate-based and IP/geo references); this is the forwarded-IP concern that cuts across them. Pairs with the inbound-header-stripping reference.

Execute commands using the AWS MCP server when connected (sandboxed execution, audit logging, observability). Fall back to the AWS CLI otherwise.

Table of Contents

• Overview
• Workflow
• The problem: WAF sees the CDN’s IP
• Enable forwarded-IP on the affected rules
• Trust the header only from a known upstream
• Troubleshooting
• Procedure
• Security Considerations
• Additional Resources

Workflow

To recover the real client IP end to end, follow the procedure exactly. See the Procedure section below.

The procedure covers:

• Identifying which rules act on the wrong address
• Enabling forwarded-IP configuration on rate-based and IP or geo rules
• Optionally forwarding ${awswaf:ip:} to the origin
• Pairing with the inbound-header-stripping rule

The problem: WAF sees the CDN’s IP

Behind a CDN, the connection IP AWS WAF reads is the CDN’s, not the user’s, so IP set rules, rate-based rules, and geographic match rules all act on the wrong address. Customers often do not know AWS WAF can recover the true client IP and conclude their rules are broken.

Constraints:

• You MUST recognize that IP-based rules act on the CDN address by default when behind a CDN, and surface the forwarded-IP option rather than letting the customer disable rules that look broken

Enable forwarded-IP on the affected rules

Forwarded-IP configuration tells the rule to read the client address from a header such as X-Forwarded-For, True-Client-IP, or a custom header.

Constraints:

• You MUST enable forwarded-IP configuration on the rate-based and IP or geo rules that need the real client address
• You SHOULD forward ${awswaf:ip:} (the resolved client IP) to the origin via interpolation when the origin needs it, rather than parsing the forwarding header downstream
• You MUST forward the interpolated client IP only to an HTTPS-only origin, and the application MUST validate the origin’s TLS certificate, so the header is not exposed in cleartext. You SHOULD use AWS Certificate Manager (ACM) to provision and manage the origin’s TLS certificate (for example on an Application Load Balancer), so the certificate is validated and automatically renewed

Trust the header only from a known upstream

A forwarding header can be set by anyone unless the upstream is trusted, which lets an attacker forge the client address.

Constraints:

• You MUST trust the forwarded header only when it comes from a known, trusted upstream
• You MUST pair this with the inbound-header-stripping rule (see stripping-inbound-waf-headers-before-trusting-them) when forwarding the client IP to the origin

Troubleshooting

Rate or geo rules act on the wrong source behind a CDN

The rules read the CDN IP. Enable forwarded-IP configuration on them (Enable forwarded-IP on the affected rules).

An attacker forges the client IP

The forwarding header is trusted from an untrusted source. Trust it only from a known upstream and add the strip rule (Trust the header only from a known upstream).

Procedure

Overview

This procedure enables forwarded-IP on the affected rules, optionally forwards the client IP to the origin, and surfaces the console link.

Parameters

• web_acl_name, web_acl_id, scope (required): Identify the web ACL.
• forwarding_header (required): X-Forwarded-For, True-Client-IP, or a custom header the trusted upstream sets.
• affected_rules (required): Which rate-based, IP set, or geo rules need the real client IP.

Constraints for parameter acquisition:

• You MUST ask for all required parameters upfront in a single prompt
• You MUST confirm which upstream sets the forwarding header and that it is trusted

Steps

1. Verify dependencies

Constraints:

• You MUST confirm credentials with aws sts get-caller-identity
• You MUST confirm the trusted upstream reliably sets the forwarding header

2. Enable forwarded-IP on the rules

Constraints:

• You MUST add forwarded-IP configuration (header name and fallback behavior) to the affected rate-based and IP or geo rules

• You MUST fetch the current LockToken before update-web-acl and pass the full rule set

• You MUST preserve the web ACL’s existing DefaultAction from the get-web-acl response and pass it back as {default_action}; do not assume Allow={}, since that would silently open all unmatched traffic on a web ACL whose default action is Block. For example, a geo-match rule reading the client IP from a forwarding header:

  Copy

  aws wafv2 get-web-acl --name {web_acl_name} --scope {scope} --id {web_acl_id} --region {region}
  aws wafv2 update-web-acl --name {web_acl_name} --scope {scope} --id {web_acl_id} \
    --lock-token {lock_token} --default-action {default_action} \
    --rules '[{"Name":"BlockHighRiskCountries","Priority":1,"Action":{"Block":{}},"Statement":{"GeoMatchStatement":{"CountryCodes":["KP","IR"],"ForwardedIPConfig":{"HeaderName":"{forwarding_header}","FallbackBehavior":"NO_MATCH"}}},"VisibilityConfig":{"SampledRequestsEnabled":true,"CloudWatchMetricsEnabled":true,"MetricName":"BlockHighRiskCountries"}}]' \
    --visibility-config SampledRequestsEnabled=true,CloudWatchMetricsEnabled=true,MetricName={web_acl_name} \
    --region {region}

  Rate-based rules take the same ForwardedIPConfig under RateBasedStatement; FallbackBehavior is MATCH or NO_MATCH for when the header is absent

3. Optionally forward the client IP and add the strip rule

Constraints:

• You SHOULD forward ${awswaf:ip:} to the origin if it needs the client IP
• You MUST add the inbound-header-stripping rule when forwarding the client IP

4. Surface the console link

Constraints:

• You MUST present the web ACL console link and tell the customer to confirm the rules read the forwarded IP:

  Copy

  https://us-east-1.console.aws.amazon.com/wafv2/homev2/web-acls?region={region}

Example

Example input

Example output

Troubleshooting

Rules still act on the CDN address

Forwarded-IP is not enabled on them. Add it (Step 2).

The client IP can be forged

Trust the header only from a known upstream and add the strip rule (Step 3).

Security Considerations

This procedure modifies a security control, so misconfiguration directly weakens the application’s defenses.

• Least-privilege IAM. You MUST grant only the specific wafv2: actions a task needs (for example wafv2:GetWebACL and wafv2:UpdateWebACL) rather than wafv2:* or the AWSWAFFullAccess managed policy.
• Ephemeral credentials. You MUST use IAM roles with temporary credentials (such as an EC2 instance profile, SSO session, or aws sts assume-role) rather than long-lived IAM user access keys when running these WAF CLI commands.
• Monitor configuration changes. You SHOULD enable AWS CloudTrail on wafv2 management events and set CloudWatch alarms on critical web ACL configuration changes (such as DeleteWebACL and UpdateWebACL rule removals) and on the web ACL’s BlockedRequests and CountedRequests metrics, so rule changes and sudden spikes in blocked or counted traffic are detected.
• Header-spoofing risk. Any x-amzn-waf-* signal forwarded to the origin can be forged inbound. You MUST add the inbound-header-stripping rule whenever a signal or client IP is forwarded (see stripping-inbound-waf-headers-before-trusting-them); without it the origin trusts a spoofable value.
• Encrypted transport. You MUST forward the signal only to an HTTPS-only origin and the application MUST validate the origin’s TLS certificate, so the signal is not exposed in cleartext. You SHOULD use AWS Certificate Manager (ACM) to provision and manage the origin’s TLS certificate (for example on an Application Load Balancer), so the certificate is validated and automatically renewed.
• Defense in depth. You SHOULD treat the forwarded signal as one input among several, not a sole gate; over-relying on a single signal without defense in depth leaves the application exposed if the signal is evaded or degraded.

Additional Resources

• Using forwarded IP addresses in AWS WAF (AWS WAF Developer Guide) (opens in a new tab)
• Dynamic label interpolation (AWS WAF Developer Guide) (opens in a new tab)