How to configure a blacklist and a whitelist - API Gateway

API Gateway provides IP address-based access control plug-ins to enhance the security of APIs. These plug-ins are used to specify IP addresses or CIDR blocks from which API requests can be sent. You can add an IP address to the whitelist or blacklist of an API to allow or deny API requests from that IP address.

1. Overview

When you configure an IP address-based access control plug-in, you can use two control modes:

Allow: In the Allow mode, you can configure a whitelist to allow requests from specified IP addresses. The following types of whitelists are supported:
- You can configure a whitelist that contains only allowed IP addresses. In this case, only API requests from the IP addresses in the whitelist are allowed.
- You can configure a whitelist that specifies applications and their IP addresses. In this case, each application can send API requests only from its IP addresses in the whitelist.
Refuse: In the Refuse mode, you can configure an IP address blacklist. API Gateway denies all API requests from the IP addresses in the blacklist.

Important

IP address-based access control plug-ins support only IPv4 addresses.

2. Configurations

You can configure an IP address-based access control plug-in in JSON or YAML format. The two formats have the same schema and can be converted to each other by using a conversion tool. The following code describes a plug-in configuration template in YAML format:

---
type: ALLOW           # The control mode. You can set this parameter to ALLOW to apply a whitelist or REFUSE to apply a blacklist.
resource: "XFF:-1"   # Optional. If this field is set, an IP address in the X-Forwarded-For header is used as the source IP address. In this example, the last IP address in the X-Forwarded-For header is used as the source IP address. 
items: 
- blocks:         # A CIDR block from which API requests are allowed.
  - 61.3.XX.XX/24   # Specify a CIDR block.
  appId: 219810   # Optional. If you specify appId, the CIDR block applies only to the application indicated by appId.
- blocks:         # An IP address from which API requests are allowed.
  - 79.11.XX.XX    # Specify an IP address.
- blocks:         # The CIDR block of a VPC from which API requests are allowed.
  - 192.168.XX.XX/32    # Specify the CIDR block of a VPC. This item applies only to dedicated instances. When an API request is sent from a VPC to a dedicated instance, the source IP address of the API request is in the specified CIDR block.

Pay special attention to the last comment. If a dedicated instance is used, API Gateway allows API requests from VPCs and can directly read the IP address in the source VPC, such as 192.168.XX.XX. You can directly configure an IP address in a VPC in a blacklist or whitelist.

3. When WAF is used

If you want to configure a blacklist or whitelist for a specific API in scenarios where middleware services such as Web Application Firewall (WAF) are used, you must specify the resource field. If you leave the resource field unspecified, the IP address provided by WAF is considered the source IP address. If you specify this field, the value in the X-Forwarded-For header is used as the source IP address.

Note

WAF adds the source IP address of a received request to the end of the X-Forwarded-For header and sends the IP address to API Gateway. API Gateway considers the value in the X-Forwarded-For header as the source IP address. In this case, we recommend that you use XFF:-1 for API Gateway to use the IP address added by WAF as the source IP address.

The value format of the resource field is "XFF:index". The value of index is the sequence number of an IP address in the X-Forwarded-For header, starting from 0 and allowing negative numbers. For example, if X-Forwarded-For contains three IP addresses, which are IP1, IP2, and IP3 in sequence, XFF:0 indicates IP1, and XFF:-1 indicates IP3, which is the last IP address.

4. Cross-VPC access

If an API request is sent from a VPC to a dedicated instance in another VPC, API Gateway can directly read the IP address in the source VPC from the request. You can rest assured when you prepare a plug-in for IP addresses in VPCs. API Gateway can also read the ID of the source VPC. You can configure a parameter-based access control plug-in to allow only specified VPCs to access your API.

5. Cross-VPC access when WAF is used

In specific scenarios, your API may serve public and internal callers at the same time, and WAF is configured for public callers. In this case, API Gateway must be used to control both internal IP addresses and public IP addresses that precede WAF. API Gateway provides a solution to suit these scenarios: using the resource field in combination with the allowResourceMissing field. The resource field is used in the X-Forwarded-For header to control public IP addresses that precede WAF. The allowResourceMissing field is used to control internal IP addresses when the X-Forwarded-For header is not passed, in which case the client IP address is considered the source IP address. Example:

---
type: ALLOW           # The control mode. You can set this parameter to ALLOW to apply a whitelist or REFUSE to apply a blacklist.
resource: "XFF:-1"   # Optional. If this field is set, an IP address in the X-Forwarded-For header is used as the source IP address. In this example, the last IP address in the X-Forwarded-For header is used as the source IP address.
allowResourceMissing: "true"  # Uses the IP address directly preceding API Gateway as the source IP address when the resource field is left empty.
items: 
- blocks:         # A CIDR block from which API requests are allowed.
  - 61.3.XX.XX/24   # Specify a CIDR block.
  appId: 219810   # Optional. If you specify this parameter, this IP address-based access control policy applies only to the app specified by this parameter.
- blocks:         # An IP address from which API requests are allowed.
  - 79.11.XX.XX    # Specify an IP address.
- blocks:         # The CIDR block of a VPC from which API requests are allowed.
  - 192.168.XX.XX/32    # Specify the CIDR block of a VPC. This item applies only to dedicated instances. When an API request is sent from a VPC to a dedicated instance, the source IP address of the API request is in the specified CIDR block.

6. Use a plug-in dataset in a plug-in

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

6.1 Create a plug-in dataset

Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > Plug-ins.
On the Plug-in List page, click the Custom Dataset tab. In the upper-right corner of the tab, click Create Dataset. In the Create Dataset dialog box, enter a Name for the dataset and select IP_WHITELIST_CIDR for the Type parameter.
Click the ID of the created dataset. On the dataset details page, click Create Dataset Entry. In the Create Dataset Entry dialog box, specify Data Value (IP address or CIDR block) and Validity Period. When the validity period elapses, data entries in the dataset become invalid.

Important

Plug-in datasets take effect only for dedicated instances. If the API to which the plug-in is bound is not deployed on a dedicated instance, the dataset configured for the plug-in does not take effect.

6.2 Configure a dataset for an IP address-based access control plug-in

To configure a dataset for an IP address-based access control plug-in, you must add the blocksDatasetId field to the items section of the plug-in configuration. The value of this field is the ID of the created IP_ACCESS_CIDR dataset. The blocksDatasetId and blocks fields are compatible with each other. For each item specified in the items section, you can specify blocksDatasetId or blocks, or both.

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