Configure IP blacklist/whitelist - CDN - Alibaba Cloud Documentation Center

To protect your service from malicious IP requests or targeted attacks, you can configure an IP blacklist/whitelist to filter requests by source IP at points of presence (POPs). This feature allows you to permit only trusted IP addresses (whitelist) or block known malicious IP addresses (blacklist), thereby protecting your origin server resources and reducing security risks.

Use cases

Parameter	Use cases
IP whitelist	Protect sensitive internal data: Allow only specified IP addresses to access sensitive data or resources. Integrate with third-party services: Ensure that only trusted IP addresses from third-party services can access your CDN resources.
IP blacklist	Prevent malicious attacks: If an IP address frequently sends abnormal requests, add it to the IP blacklist to block its access. Restrict access by region: Block IP address ranges from high-risk countries or regions, such as those restricted for policy reasons.

Billing

While configuring the IP Blacklist or Whitelist feature is free, blocked requests still incur fees.

Billing logic: Blocking occurs during the HTTP request processing stage (Layer 7). At this point, the CDN POP has already processed the request and consumed resources.
Billable items:
- Data transfer fees: Each blocked request generates data transfer for both the original request (including the HTTP header) and the 403 response page. This data transfer is billed at the standard CDN rate.
- HTTPS request fees: For domains using HTTPS, the TLS handshake completes before the IP block is applied. Therefore, each blocked request still counts as a billable HTTPS request.

Notes

You can configure either an IP blacklist or an IP whitelist for a domain, but not both. They are mutually exclusive.
After an IP blacklist is configured, requests from the blacklisted IPs can still reach POPs. The POPs then reject these requests and return a 403 status code. Logs will still record these requests, but this is expected behavior and confirms that the IP blacklist is working.
Some internet service providers (ISPs) in specific regions may assign private IP addresses to end-users. As a result, POPs may receive a user's private IP address.
Note
Private IP addresses fall into three ranges:
- Class A private IP address: 10.0.0.0 to 10.255.255.255, subnet mask: 10.0.0.0/8
- Class B private IP address: 172.16.0.0 to 172.31.255.255, subnet mask: 172.16.0.0/12
- Class C private IP address: 192.168.0.0 to 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 or Whitelist section, click Modify.
The following examples help you quickly complete the configuration. For settings specific to your business requirements, refer to Parameters.
- Scenario 1: Protect an admin backend (Whitelist + Rules Engine)
  - Goal: Allow only requests from the office egress IPs 203.x.x.10 and 203.x.x.11 to access the /admin/ path.
  - Configuration:
    - Type: Select Whitelist.
    - Rules: Enter 203.x.x.10 and 203.x.x.11 (one per line).
    - Advanced Settings-IP Rules: Select Determine based on the IP address that is used to connect to the POP.
    - Advanced Settings-Rule Condition: On the Rules Engine page, create a rule that matches requests where the URI contains /admin/* (case-insensitive). Then, select this rule for the rule condition.
  - Result: Only requests from these two IP addresses can access the /admin/ directory. All other requests to this directory are rejected with a 403 status code.
- Scenario 2: Allow access from a partner's IPv6 network segment (Whitelist)
  - Goal: Allow access only from the partner's IPv6 network segment FC00:0AA3:0000:0000:0000:0000:0000:0000/48.
  - Configuration:
    1. Type: Select Whitelist.
    2. Rules: Enter FC00:0AA3:0000:0000:0000:0000:0000:0000/48.
    3. Advanced Settings-IP Rules: 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.
- Scenario 3: Block an attack source in an emergency (Blacklist)
  - Goal: Immediately block a CC attack originating from the 198.x.x.0/24 CIDR block.
  - Configuration:
    1. Type: Select Blacklist.
    2. Rules: Enter 198.x.x.0/24.
    3. Advanced Settings-IP Rules: Select Determine based on the IP address that is used to connect to the POP.
  - Result: All requests from the 198.x.x.0/24 CIDR block are rejected by the CDN POP.

Parameters

Parameter	Description
Type	Select Blacklist or Whitelist. Blacklist: Denies requests from IP addresses in the list with a 403 status code. Whitelist: Allows only requests from IP addresses in the list. Denies all other requests.
Rules	Format requirements You can enter IP addresses or IP address ranges. Use line breaks to separate multiple IP addresses or IP address ranges. Supports IPv4 addresses and address ranges: IPv4 address example: `192.168.0.1`. IPv4 address range example: `192.168.0.0/24`. The wildcard address `0.0.0.0/0` is not supported. To match all IPv4 addresses, use the following two subnets: `0.0.0.0/1` `128.0.0.0/1` Supports IPv6 addresses and address ranges: IPv6 address example: `FC00:AA3:0:23:3:300:300A:1234`. IPv6 address range example: FC00:0AA3:0000:0000:0000:0000:0000:0000/48 IPv6 addresses are case-insensitive. You can use uppercase, lowercase, or a mix of both. For example, `FC00:AA3:0:23:3:300:300A:1234` and `fc00:0aa3:0000:0023:0003:0300:300a:1234` are equivalent. The `::` shorthand format is not supported. For example, `FC00:0AA3::0023:0003:0300:300A:1234` is invalid. The wildcard address `0000:0000:0000:0000:0000:0000:0000:0000/0` is not supported. To match all IPv6 addresses, use the following two subnets: `0000:0000:0000:0000:0000:0000:0000:0000/1` `8000:0000:0000:0000:0000:0000:0000:0000/1` Rule length limit The Rule field supports up to 30 KB of characters. This limit allows for approximately 700 IPv6 addresses/ranges or 2,000 IPv4 addresses/ranges. If you need to block a larger number of IP addresses, enable the Edge Security Accelerator (ESA) feature, which supports higher IP address limits and region-based blocking. For more information, see Feature comparison of CDN, DCDN, and ESA and IP access rule configuration.
IP Rules	You can select one of the following rules: Determine based on the XFF header (default) Use this rule when clients access your service through trusted proxies that correctly set the `x-forwarded-for` header. Determine based on the IP address that is used to connect to the POP Use this rule when clients connect directly to the CDN without a proxy server, or when you want to control access based on a proxy server's IP address. Determine based on the XFF header and the IP address that is used to connect to the POP Use this rule for mixed network environments where some clients connect directly and others use a proxy server.
Rule Condition	A rule condition determines whether a configuration applies to a request by evaluating various parameters in the request. Important When a feature references rule conditions configured in the rules engine, the execution order follows the priority of the associated rule conditions, not the order of the feature configurations. Do not use conditions: Disables conditional rules. You can add or edit conditional rules in Rules engine.

How Alibaba Cloud CDN identifies client IPs

Alibaba Cloud CDN uses two methods to identify client IPs, each with its own advantages and disadvantages:

TCP connection IP
- Definition: The IP address used to establish the TCP connection between a client and an edge POP.
- Advantage: This IP address cannot be spoofed, making it the most secure option.
- Disadvantage: When a client connects through a proxy server, such as a corporate network egress or a NAT device, this IP belongs to the proxy server, not the original client.
X-Forwarded-For (XFF) request header
- Definition: An HTTP request header field that records the IP address of each proxy server that a request passes through. The CDN typically uses the leftmost IP address in this header as the client IP.
- Advantage: Can identify the original client IP from behind a proxy server.
- Disadvantage: This request header can be spoofed by the client, posing a significant security risk. An attacker can forge the XFF header to bypass IP-based access control.

When a client connects directly to the CDN, these two IPs are usually the same. However, if a client connects through a proxy server, the IPs will differ. For example, if the original client IP is 10.10.10.10 and the proxy server IP is 192.168.0.1, then:

The value of the X-Forwarded-For request header might be 10.10.10.10, 192.168.0.1.
The original client IP is 10.10.10.10.
The TCP connection IP is 192.168.0.1.

To address these scenarios, Alibaba Cloud CDN provides three IP address verification modes to balance security with business flexibility.

IP verification mode	Use cases	Mechanism	Security assessment
Use the X-Forwarded-For header as the criterion (default)	All clients connect through trusted proxy servers that correctly set the XFF header.	Only the leftmost IP address in the `X-Forwarded-For` request header is used for matching.	The `X-Forwarded-For` header can be spoofed by the client, allowing an attacker to easily bypass deny list rules.
Use the TCP connection IP as the criterion	Clients connect directly to the CDN without a proxy server, or you want to control access based on the proxy server's IP.	Only the TCP connection IP is used for matching.	The TCP connection IP cannot be spoofed, providing the most reliable protection.
Use both the X-Forwarded-For header and the TCP connection IP as criteria	For mixed network environments where some clients connect directly and others connect through a proxy server.	Deny list : A request is blocked if a rule matches either the IP in the `X-Forwarded-For` header or the TCP connection IP. Allow list : A request is allowed if a rule matches either the IP in the `X-Forwarded-For` header or the TCP connection IP.	This mode balances the flexibility of identifying the original client IP with the security of the TCP connection IP, making it the recommended choice for most scenarios.

FAQ

Related APIs

Add an IP Blacklist or Whitelist configuration

Call the BatchSetCdnDomainConfig operation to configure an IP Blacklist or Whitelist. For more information, see Configure an IP whitelist and Configure an IP blacklist.

Update an IP Blacklist or Whitelist configuration

Call the BatchSetCdnDomainConfig operation to update an IP Blacklist or Whitelist. For more information, see Configure an IP whitelist and Configure an IP blacklist.

Important

This operation updates only the specified parameters. For example, if you specify the ip_list parameter but not the ip_acl_xfwd parameter in a request, the value of ip_acl_xfwd remains unchanged.

This operation can update only the IP list, IP rule, and rule condition. You cannot change the configuration type. For example, you cannot use this operation to change an IP blacklist configuration to an IP whitelist configuration.

To change the configuration type (for example, from an IP blacklist to an IP whitelist), do the following:

Delete the existing IP blacklist configuration.
Add a new IP whitelist configuration.

Delete an IP Blacklist or Whitelist configuration

Step 1: Query the ConfigId

Call the query domain configurations operation to retrieve the ConfigId. If you already have the ConfigId, you can skip this step and proceed to Step 2.

Step 2: Delete the configuration

Call the DeleteSpecificConfig operation and specify the ConfigId.