How to configure a whitelist or blacklist for an API - API Gateway

The IP address-based access control plug-in from API Gateway controls access to your APIs based on the caller's source IP address or IP address range. You can configure a whitelist or blacklist for an API to allow or deny requests from specific sources.

1. Overview

You can use a whitelist or blacklist:

Whitelist: You can configure a whitelist based on IP addresses or a combination of an appId and an IP address. API Gateway rejects requests from sources not on the whitelist.
- IP whitelist: Only requests from the specified source IP addresses are allowed.
- If an appId is configured, the rule applies only to that application, allowing it to access the API only from the specified IP addresses without affecting other authorized applications.
Blacklist: You can configure an IP blacklist. API Gateway rejects all requests from IP addresses on the blacklist.

Important

The IP address-based access control plug-in supports IPv4 and IPv6 addresses.

2. Plug-in configuration

You can use either JSON or YAML format to configure your plugin. The schema is the same for both formats. To convert between the formats, you can search for a yaml to json conversion tool. The following table provides a template in YAML format.

---
type: ALLOW           # The control mode. Valid values: ALLOW (for a whitelist) and REFUSE (for a blacklist).
resource: "XFF:-1"   # Optional. If this parameter is specified, an IP address from the X-Forwarded-For header is used as the client's source IP for evaluation. This example uses the last IP address in the header.
items: 
- blocks:         # An IP address range.
  - 61.3.XX.XX/24
  appId: 219810   # Optional. If specified, this entry applies only to this appId.
- blocks:         # An IP address.
  - 79.11.XX.XX
- blocks:         # A user VPC.
  - 192.168.XX.XX/32    # This applies to dedicated instances. For requests sent from a user VPC to API Gateway, the source IP address that API Gateway detects is in this address range.

For dedicated instances, API Gateway allows requests from within a user VPC. In this case, API Gateway can directly read the source IP address from within the VPC, such as 192.168.XX.XX. You can use these internal VPC addresses directly when you configure your whitelist or blacklist.

3. Handle requests forwarded by a WAF

If a middleware service like a Web Application Firewall (WAF) is deployed before API Gateway, use the resource field to apply API-level IP filtering. This field is optional. If you do not specify this field, the IP address of the preceding hop is used for evaluation. If you specify this field, you can use a value from the X-Forwarded-For header as the basis for IP evaluation.

Note

WAF adds the source IP address of a request it receives to the end of the X-Forwarded-For header and then forwards the request to API Gateway. API Gateway can then identify the source IP address by checking the value in the X-Forwarded-For header. In this case, we recommend that you use "XFF:-1" to identify the IP address of the hop immediately preceding WAF.

The resource parameter must be in the XFF:index format. The index specifies the position of the IP address in the X-Forwarded-For header. The index is zero-based and can be negative. For example, if the value of X-Forwarded-For is IP1,IP2,IP3, an index of 0 selects IP1, and an index of -1 selects IP3, which is the last IP address.

4. Cross-VPC access

In cross-VPC access scenarios, API Gateway can directly read the source IP address from within the originating VPC. You can therefore use internal VPC IP addresses directly in the IP address-based access control plug-in. API Gateway can also read the source VPC ID, allowing you to use a parameter-based access control plug-in to permit access only from specific VPCs.

5. Combined WAF and cross-VPC traffic

If your API serves both public traffic (routed through a WAF) and internal traffic, you can use the resource and allowResourceMissing fields to manage both scenarios. Set the resource field to retrieve the client IP from the X-Forwarded-For header for WAF traffic. Then, set allowResourceMissing to true. This allows API Gateway to fall back to the preceding hop's IP for internal traffic, which lacks the X-Forwarded-For header.

---
type: ALLOW           # The control mode. Valid values: ALLOW (for a whitelist) and REFUSE (for a blacklist).
resource: "XFF:-1"   # Optional. If this parameter is specified, an IP address from the X-Forwarded-For header is used as the client's source IP for evaluation. This example uses the last IP address in the header.
allowResourceMissing: "true"  # Allows the resource to be missing. If missing, the IP address of the preceding hop is used for evaluation.
items: 
- blocks:         # An IP address range.
  - 61.3.XX.XX/24   # Specify a CIDR block.
  appId: 219810   # Optional. If specified, this entry applies only to this appId.
- blocks:         # An IP address.
  - 79.11.XX.XX    # Specify an IP address.
- blocks:         # A user VPC.
  - 192.168.XX.XX/32    # This applies to dedicated instances. For requests sent from a user VPC to API Gateway, the source IP address that API Gateway detects is in this address range.

6. Use plug-in datasets

For more information about how to configure the plug-in, see IP address-based access control plug-in.

6.1. Create a plug-in dataset

Log on to the API Gateway console and select a region. In the left-side navigation pane, choose Manage APIs > > Plug-ins.
On the Plug-in List page, click the Plug-in Datasets tab. In the upper-right corner of the tab, click Create Dataset. In the dialog box that appears, enter a Name for the dataset and select IP_WHITELIST_CIDR from the Type drop-down list.
Click the ID of the target dataset to go to its details page. Click Create Dataset Entry. In the dialog box that appears, enter a Data Value (an IP address or a CIDR block) and specify the Validity Period. Data entries expire automatically.

For Validity Period, you can select Short-term (by specifying an expiration date) or Long-term. You can also optionally enter a Description.

Important

Plug-in datasets take effect only on dedicated instances. If a plug-in that uses a dataset is bound to an API that is not on a dedicated instance, the dataset configuration will not take effect.

6.2. Configure the plug-in with a dataset

To use a plug-in dataset in an IP address-based access control plug-in, add the blocksDatasetId field to an item in the items array. The blocksDatasetId and blocks fields are compatible. Within each item, you can use blocksDatasetId and blocks together or individually.

---
type: ALLOW 
items: 
- blocksDatasetId: 87b65008e92541938537b1a4a236eda5
  appId: 219810
- blocksDatasetId: 87b65008e92541938537b1a4a236eda3
  blocks:
  - 127.0.XX.XX
  - 192.168.XX.XX/24