Configure an IP blacklist or whitelist to block or allow access from specific IP addresses - CDN

When your service is subject to malicious IP-based traffic abuse or specific attacks, you can configure an IP blacklist or whitelist to filter requests at CDN edge nodes based on the request source. This feature allows access only from trusted IP addresses by using a whitelist or precisely blocks known malicious IP addresses by using a blacklist, thereby protecting origin resources and reducing security risks.

Use cases

Select an IP whitelist or blacklist based on the following use cases:

Configuration	Use cases
IP whitelist	Protect sensitive internal data: Allow only specified IP addresses to access sensitive data or resources to ensure data security. Integrate with third-party services: Ensure that only IP addresses of trusted third-party services can access CDN resources.
IP blacklist	Prevent malicious attacks: If an IP address frequently sends abnormal requests, add it to the blacklist to prevent the malicious IP address from accessing your resources. Restrict access by region: Block IP addresses from high-risk regions, such as countries subject to specific policy restrictions, by adding the IP address ranges of those countries or regions to the blacklist.

Billing

Configuring an IP blacklist or whitelist is free of charge, but blocked requests still incur minor fees.

Billing principle: Blocking occurs during HTTP request processing at Layer 7. At this point, the CDN node has already processed the request and consumed resources.
Billable items:
- Traffic fees: A blocked request generates traffic for one request, including the HTTP headers, and one response, which is the 403 page. The traffic is billed at the standard CDN traffic rate.
- HTTPS request fees: If the domain name uses HTTPS, the TLS handshake is completed before IP-based blocking occurs. Therefore, each blocked HTTPS request is still counted as one HTTPS request for billing.

Considerations

Important

IP Blacklist/Whitelist and Referer Blacklist/Whitelist are separate configuration entries in the access control module. Do not confuse them:

IP Blacklist/Whitelist: Controls access based on source IP addresses. The rule field supports IPv4 or IPv6 addresses and CIDR blocks, such as 1.1.1.0/24. Configuration path: Domain Names > Access Control > IP Blacklist/Whitelist.
Referer Blacklist/Whitelist: Controls hotlinking based on the HTTP Referer header. The rule field supports only domain names or URLs, not IP addresses. Configuration path: Domain Names > Access Control > Referer Blacklist/Whitelist.

To control access by IP address, use IP Blacklist/Whitelist. Do not enter an IP address or CIDR block in the rule field of Referer Blacklist/Whitelist. Otherwise, the system returns the parameter format validation error InvalidArgValue.Malformed.

The following considerations also apply to IP blacklist and whitelist configurations:

A domain name can have only one IP blacklist or IP whitelist rule. The two types are mutually exclusive and cannot be configured at the same time.
After you configure an IP blacklist, requests from blacklisted IP addresses can still reach the CDN node, but the node rejects the requests and returns a 403 status code. The CDN logs record the requests from these IP addresses. This does not indicate that the IP blacklist is ineffective.
In specific regions, a small number of Internet service providers (ISPs) may assign private IP addresses to end users. As a result, the CDN node receives the user's private IP address.
Note
Private IP addresses fall within the following three ranges:
- Class A private IP addresses: 10.0.0.0–10.255.255.255. Subnet mask: 10.0.0.0/8.
- Class B private IP addresses: 172.16.0.0–172.31.255.255. Subnet mask: 172.16.0.0/12.
- Class C private IP addresses: 192.168.0.0–192.168.255.255. Subnet mask: 192.168.0.0/16.

Procedure

Log on to the CDN console.
On the Domain Names page, find the target domain name and click Manage in the Actions column.
In the domain's navigation pane, click Access Control.
In the IP Blacklist/Whitelist section, click Modify Configuration.
You can quickly configure a rule based on the following examples. You can also refer to Parameters and add a configuration suitable for your business.
- Example 1: Protect an administration backend (whitelist + Rule Engine)
  - Goal: Allow only the office egress IP addresses 203.x.x.10 and 203.x.x.11 to access the /admin/ path.
  - Configuration:
    - Type: Select Whitelist.
    - Rule: Enter 203.x.x.10 and 203.x.x.11 on separate lines.
    - Advanced Settings - IP Rule: Select Determine based on the IP address that is used to connect to the POP.
    - Advanced Settings - Rule Condition: On the Rule Engine page, configure a rule that matches when the URI contains any occurrence of /admin/*, regardless of case. Then select this rule as the rule condition.
  - Result: Only requests from these two IP addresses can access the /admin/ directory. Requests from all other IP addresses to this directory are rejected with a 403 status code.
- Example 2: Allow access from a partner's IPv6 CIDR block (whitelist)
  - Goal: Allow access only from the partner's IPv6 CIDR block FC00:0AA3:0000:0000:0000:0000:0000:0000/48.
  - Configuration:
    1. Type: Select Whitelist.
    2. Rule: Enter FC00:0AA3:0000:0000:0000:0000:0000:0000/48.
    3. Advanced Settings - IP Rule: Select Determine based on the IP address that is used to connect to the POP.
  - Result: Only requests from this IPv6 address range can access your domain resources.
- Example 3: Immediately block an attack source (blacklist)
  - Goal: A CC attack is detected from the 198.x.x.0/24 CIDR block and must be blocked immediately.
  - Configuration:
    1. Type: Select Blacklist.
    2. Rule: Enter 198.x.x.0/24.
    3. Advanced Settings - IP Rule: Select Use the actual connection IP address as the basis for evaluation.
  - Result: The CDN node rejects all IP requests from the 198.x.x.0/24 CIDR block.

Parameters

The following table describes the parameters for an IP blacklist or whitelist:

Parameter	Description
Type	Select Blacklist or Whitelist. Blacklist: IP addresses in the list are denied access and receive a 403 status code. Whitelist: Only IP addresses in the list are allowed access. All other IP addresses are denied.
Rule	Rule format requirements You can enter IP addresses or CIDR blocks. Separate multiple IP addresses or CIDR blocks with line feeds. IPv4 addresses and CIDR blocks are supported: IPv4 address example: `192.168.0.1`. IPv4 CIDR block example: `192.168.0.0/24`. The wildcard CIDR block `0.0.0.0/0` is not supported. To represent all IPv4 addresses, use the following two CIDR blocks: `0.0.0.0/1` `128.0.0.0/1` IPv6 addresses and CIDR blocks are supported: IPv6 address example: `FC00:AA3:0:23:3:300:300A:1234`. IPv6 CIDR block example: `FC00:0AA3:0000:0000:0000:0000:0000:0000/48`. Letters in an address are case-insensitive. Uppercase, lowercase, and mixed-case letters are supported. Examples: `FC00:AA3:0:23:3:300:300A:1234` and `fc00:0aa3:0000:0023:0003:0300:300a:1234`. The `::` abbreviation is not supported. For example, `FC00:0AA3::0023:0003:0300:300A:1234` is not supported. The wildcard CIDR block `0000:0000:0000:0000:0000:0000:0000:0000/0` is not supported. To represent all IPv6 addresses, use the following two CIDR blocks: `0000:0000:0000:0000:0000:0000:0000:0000/1` `8000:0000:0000:0000:0000:0000:0000:0000/1` Rule length limit The rule input field supports up to 30 KB of characters. Because IP addresses and CIDR blocks vary in length, the field can hold approximately 700 IPv6 addresses or CIDR blocks, or approximately 2,000 IPv4 addresses or CIDR blocks, based on average entry lengths. If you need to block more IP addresses, enable the ESA security protection feature, which supports large-scale IP blocking and region-based blocking. For more information, see CDN, DCDN, and ESA: Feature comparison and Configure an IP access rule.
IP Rule	You can select one of the following three rules: Use the user's x-forwarded-for request header as the basis for evaluation (default) This rule is recommended when all clients access CDN through trusted proxies that correctly set the `x-forwarded-for` header. Use the actual connection IP address as the basis for evaluation This rule is recommended when clients connect directly to CDN without an intermediate proxy server, or when you want to control access based on the proxy server's IP address. Use both x-forwarded-for and the actual connection IP address as the basis for evaluation This rule is recommended for a mixed network environment in which some users connect directly and others access CDN through proxies.
Rule Condition	A rule condition identifies various parameter information in a user request. This determines whether a configuration takes effect for that request. Important When you reference rule conditions, they are matched based on the priority of the associated rule conditions, not the configuration order of the feature itself. Do not use: Does not use a rule condition. To add or edit rule conditions, manage them in the Rules Engine.

Further reading: How Alibaba Cloud CDN identifies client IP addresses

CDN nodes identify client IP addresses in the following two ways. Each has advantages and disadvantages:

Actual connection IP address (TCP connection IP)
- Definition: The IP address that the client uses to establish a TCP connection with the CDN edge node.
- Advantage: The address cannot be forged and provides the highest security.
- Disadvantage: If a user accesses CDN through a proxy, such as a corporate network egress or NAT device, this address is the proxy server's IP address and does not reflect the actual client source.
X-Forwarded-For (XFF) request header
- Definition: An HTTP request header that records the IP address of each proxy server through which a request passes. CDN typically uses the leftmost IP address as the client IP address.
- Advantage: The header can identify the actual client IP address through proxies.
- Disadvantage: A client can forge this header, which poses a serious security risk. A malicious user can forge the XFF header to bypass access control based on this IP address.

When a client directly accesses CDN, these two IP addresses are typically the same. If the client accesses CDN through a proxy server, the addresses differ. For example, if the actual client IP address is 10.10.10.10 and the proxy server IP address is 192.168.0.1:

The value of the X-Forwarded-For request header may be 10.10.10.10, 192.168.0.1.
The actual client IP address is 10.10.10.10.
The actual connection IP address is 192.168.0.1.

For the preceding IP identification methods, CDN provides three verification modes to balance security and business flexibility.

IP address verification mode	Use case	How it works	Security assessment
Use the user's x-forwarded-for request header as the basis for evaluation (default)	All clients access CDN through trusted proxies that correctly set the XFF header.	Only the leftmost IP address in the `x-forwarded-for` request header is extracted and matched.	The `x-forwarded-for` request header can be forged by clients. A malicious user can easily bypass blacklist restrictions.
Use the actual connection IP address as the basis for evaluation	Clients connect directly to CDN without an intermediate proxy server, or access must be controlled based on the proxy server's IP address.	Only the IP address used by the client to establish the TCP connection with the CDN node is matched.	The connection IP address cannot be forged and provides the most reliable protection.
Use both x-forwarded-for and the actual connection IP address as the basis for evaluation	A mixed network environment in which some users connect directly and others access CDN through proxies.	Blacklist: A request is blocked if either the IP address in the `x-forwarded-for` header or the actual connection IP address matches the rule. Whitelist: A request is allowed if either the IP address in the `x-forwarded-for` header or the actual connection IP address matches the rule.	This mode combines the flexibility of identifying actual client IP addresses with the security of connection IP addresses and is the best choice for most scenarios.

FAQ

For troubleshooting IP blacklist and whitelist issues, such as 403 errors, see Troubleshoot access control issues.
For information about IP blacklist and whitelist quotas, see FAQ about access control.