How to configure IP Allow List (whitelist) in AWS WAF

AWS Web Application Firewall (WAF) is an AWS security service which protects web applications from various types of exploitation using AWS Managed and custom rules. In AWS WAF you define a Web access control list (ACL) and then associate it (AWS WAF) with various AWS resources such as Amazon CloudFront, API Gateway, Application Load Balancer etc.

This pattern is focused on setting up an AWS WAF rule to restrict incoming traffic from the known IP addresses only. This list of IP addresses is called Allow-list IPs or Whitelisted IPs.

Table Of Contents

Limitations
Requirements
Target Architecture
Implementation Considerations
- Allow-List rule priority:
Best practices
Implementation
- Create AWS WAF Rule for IP Allow-List
Troubleshooting
Related Resources
Additional information

Limitations

This pattern does not cover integration of WAF with CloudFront or any other resource.

Requirements

User must have knowledge of AWS WAF, otherwise it is a good idea to go through AWS WAF Workshop before using this pattern.
User must have knowledge of Amazon CloudFront
User must have an active AWS account and access to AWS WAF, Amazon CloudFront
A web browser that is supported for use with the AWS Management Console. (See the list of supported browsers)

Target Architecture

Following is an example flow diagram. This pattern will reference this diagram in order to implement the allow-list rule in AWS WAF.

In this example there is an enterprise which has a corporate data center. Some of the web applications of this enterprise can only be accessed through enterprise provided laptops or the applications deployed in the data center. Enterprise users get authenticated and then get access to the web application from the authenticated laptop/desktop/other application or services. This request reaches AWS CloudFront through AWS Route 53. The distribution in CloudFront has a WAF associated with it and this WAF has a rule to validate the IP Address of the requestor. That means if the requestor’s IP is in the list of allowed IPs, this request will be honored, otherwise it will be blocked.

Implementation Considerations

Let’s dive in and look at a typical HTTP request:

httpRequest: {
  "clientIp": "3.135.130.198",
  "country": "US",
  "headers": [
    {
      "name": "Host",
      "value": "mywebapp.mydomain.com"
    },
    {
      "name": "X-Forwarded-For",
      "value": "52.90.140.111, 10.200.196.72"
    },
    {
      "name": "X-Forwarded-Proto",
      "value": "https"
    },
    {
      "name": "X-Forwarded-Port",
      "value": "443"
    },
    {
      "name": "X-Amzn-Trace-Id",
      "value": "Root=1-12345x33-123123n1231jkh321"
    },
    {
      "name": "accept",
      "value": "application/json, text/plain, */*"
    },
    {
      "name": "user-agent",
      "value": "Mozilla/5.0 ...."
    },
    {
      "name": "sec-fetch-site",
      "value": "same-origin"
    },
    {
      "name": "sec-fetch-mode",
      "value": "cors"
    },
    {
      "name": "sec-fetch-dest",
      "value": "empty"
    },
    {
      "name": "referer",
      "value": "https://something.somedomain.com/someuri"
    },
    {
      "name": "accept-encoding",
      "value": "gzip, deflate, br"
    },
    {
      "name": "accept-language",
      "value": "en-US"
    },
    {
      "name": "cookie",
      "value": "key1=value1; key2=value2"
    },
    {
      "name": "CurrentHost",
      "value": "mymicroapp.mydomain.com"
    },
    {
      "name": "X-Forwarded-Server",
      "value": "localhost"
    },
    {
      "name": "Connection",
      "value": "close"
    }
  ],
  "uri": "/uri/subdomain/some-uri",
  "args": "",
  "httpVersion": "HTTP/1.1",
  "httpMethod": "GET",
  "requestId": "CYasdasasKJHksKJkjkjhYsaddasd8kjaSDFSFSGDNBjhhKJ=="
}

The following two fields in the HTTP request help determine the allow-list:

ClientIP
X-Forwarded-For

In most cases the ClientIp field of the http request contains the IP address of the request originator. But if the request passes through one or more hops, it is possible that the value of the ClientIP will be replaced by the hopping device. In this case the originator’s IP is not lost because during each hop, the value of the ClientIp field is pushed to the request’s http header named X-Forwarded-For, meaning that X-Forwarded-For will have a list of all ClientIP values which has been replaced by the hopping devices. As values are pushed in the order they have been replaced, the first IP in X-Forwarded-For will be the IP address of the request originator.

Allow-List rule priority:

AWS WAF Web ACL is a list of rules in ascending priority order. When a request reaches to Web ACL, rules are evaluated in the sequence of highest (smallest priority number) to the lowest priority order. In case the request is blocked by a specific rule, the remaining rules in the Web ACL list will not be evaluated and the AWS WAF will return an error to Amazon CloudFront

When adding an allow-list rule to the Web ACL, generally this will be the first rule in the list, because when requests reach the Web ACL, the allow-list rule will filter out all unwanted requests based on the originator’s IP and only legitimate requests will flow down to be evaluated by the rest of the Web ACL rules. This saves time and resources used by those Web ACL rules..

Best practices

As HTTP headers are vulnerable and can be spoofed, the allow list rule alone is not enough to block bad traffic. So other rules like rate-based rules (DDoS) and AWS Managed rules like AWSManagedRulesAmazonIpReputationList and AWSManagedRulesAnonymousIpList must be added in AWS WAF Web ACL for better protection.
If implementing Allow-List-IPs using IaC (CloudFormation / Terraform / etc.), do not create one giant list of IP addresses in the code: create smaller lists with a given name, so that the list of IP addresses can be identified by the name inside the code. Based on the requirement merge them and create specific allow-list for the specific requirement. Also ensure while creating Web ACL rule list, only one allow-list rule is added (multiple allow-list in a Web ACL do not work).
While implementing Allow-List, make sure you are considering the environment (Dev / QA / Prod) and NOT generalizing the list for all the environments if that is not intended.

Implementation

Create AWS WAF Rule for IP Allow-List

Create IP Set

Login into your AWS Account and go to WAF & Shield (https://console.aws.amazon.com/wafv2)
On the Left side menu click on “IP sets”
If this WAF rule is going to be attached to Amazon CloudFront, then select Global region from the drop-down. Otherwise select the region of the resource on which WAF is going to be attached
Click on the button “Create IP set”, this will open form to create IP Set
Give a unique name to this IP set, enter description, region must be auto populated and then select IP Version. At the time of writing this pattern, the generally used IP version is IPv4, so select that.
Next list of IP addresses in CIDR format (read this doc is you want to know more about CIDR). Enter all the IP addresses / IP addresses ranges that needs to be in the allow-list.
When done, click on “Create IP set” button.

Create WAF Rule

Create Web ACL in AWS WAF using AWS Console, follow instructions in the “Getting started with AWS WAF” document
After Web ACL is created it will be listed under the Web ACLs list. Click on that, it will open “Overview” Tab of this Web ACL.
To add the allow-list rule, click on the “Rules” tab, this will list all the rules you must have created in step-1.
Now click on “Add Rules” → “Add my own rules and rule groups”, this will open the form to create the rule.
Select “Rule builder” as the Rule type
In the Rule Builder section, do the following: (In this section we need to implement: If ClientIP OR first IP of X-Forwarded-For is not in the IP set created, then block that request, else allow).
To implement above, click on “Rule JSON editor” button. Because we are using more than one logical operator (NOT and OR), the Rule visual editor does not support this (at the time of writing this pattern).
Put the following JSON in the JSON box and click on “Add rule“ button, this will again show a popup to Save rule. Click on “Save” button, that will save this rule and add in your Web ACL list.

Important

Update ARN in following JSON, get the ARN of the IP Set you created in the “Create IP Set” section and use that here.
Change the Name of the rule based on your requirement

{
  "Name": "Allow-IP-List",
  "Priority": 0,
  "Statement": {
  	"NotStatement": {
  	  "Statement": {
	    "OrStatement": {
	      "Statements": [
	        {
	          "IPSetReferenceStatement": {
	            "ARN": "arn:aws:wafv2:us-east-1:<your account>:global/ipset/<IP Set name>/<IP set id>"
	          }
	        },
	        {
	          "IPSetReferenceStatement": {
	            "ARN": "arn:aws:wafv2:us-east-1:<your account>:global/ipset/<IP Set name>/<IP set id>",
	            "IPSetForwardedIPConfig": {
	              "HeaderName": "X-Forwarded-For",
	              "FallbackBehavior": "MATCH",
	              "Position": "FIRST"
	            }
	          }
	        }
	      ]
	    }
	  }
    }
  },
  "Action": {
    "Block": {}
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "Allow-IP-List"
  }
}

Check Priority of the Rule in the Rules list. WAF automatically arranges priority if 2 rules have the same priority. As this rule was added as priority 0, it is possible that the other rule had the same priority and this rule may have been given lower priority. In this case edit above JSON and make priority lower than the other rule, change it to "Priority": -1, this way WAF will move this role to priority 0 or higher than the other rule.

Troubleshooting

Issue	Solution
Created WAF rule and attached to CloudFront, after attaching WAF, it is blocking not only traffic coming from IP which are not in allow-list, but blocking traffic from IPs which are in allow list also. This means it is blocking all the traffic.	There may be multiple reasons for this: Check section “Default web ACL action for requests that don’t match any rules” in the AWS WAF’s Web ACL. If in this section you configured “Action = Block”, it will block all the traffic which is NOT blocked by Web ACL Rules. Change this to “Action = Allow” It is possible traffic is blocked by another rule in Web ACL, so go to Web ACL and move to “Overview” tab. At the bottom of the page there is a section called “Sampled requests”. Filter this with the string BLOCK which will display all blocked traffic. Then click “URI” which will open a popup box. Check “Rule inside rule group” and refer to AWS documentation to find out what the rule does. If it is required to create an exception to allow your traffic, create that exception.

Issue

Solution

Created WAF rule and attached to CloudFront, after attaching WAF, it is blocking not only traffic coming from IP which are not in allow-list, but blocking traffic from IPs which are in allow list also. This means it is blocking all the traffic.

There may be multiple reasons for this:

Check section “Default web ACL action for requests that don’t match any rules” in the AWS WAF’s Web ACL. If in this section you configured “Action = Block”, it will block all the traffic which is NOT blocked by Web ACL Rules. Change this to “Action = Allow”

It is possible traffic is blocked by another rule in Web ACL, so go to Web ACL and move to “Overview” tab. At the bottom of the page there is a section called “Sampled requests”. Filter this with the string BLOCK which will display all blocked traffic. Then click “URI” which will open a popup box. Check “Rule inside rule group” and refer to AWS documentation to find out what the rule does. If it is required to create an exception to allow your traffic, create that exception.

Related Resources

Additional information

Q. Is AWS WAF the only service where Allow List of IPs can be created?
A. No, there are many other ways Allow List IPs can be created, for example: Security Group, Network ACL, AWS Firewall Manager etc.
Q. If I add IPs for this rule, can I add / remove IPs from the allow list
A. Yes, just add / remove IPs from the “IP set” which is attached to the Web ACL Rule.
Q. I don’t have a static list of IP addresses, my resources are dynamically created and destroyed, how can I create the allow-list?
A. If the IP address for the resource is allocated from a CIDR range, that CIDR range can be added in the allow-list. If the IP address is a public IP address and is generated from a generic pool, DO NOT add the CIDR of the generic pool to the allow-list. Discuss alternate options with your DevOps solution provider, possibly your resource creation and destruction can be attached with an event bridge and based on the event a lambda function can update “IP set” OR any other custom solution can be built.
Q. Can this be Implemented via Rule Group?
A. Yes. This can be implemented using a rule group, but a rule group addition consumes default 200 WCU’s. This implementation consumes 2 WCU’s which reduces the cost.

Credits: Shashi Dalmia, Co-Author, AWS

How to configure IP Allow List (whitelist) in AWS WAF

Limitations

Requirements

Target Architecture