All Products
Search

This Product

    CDN:Configure an IP blacklist/whitelist

    Document Center

    CDN:Configure an IP blacklist/whitelist

    Last Updated:Sep 17, 2025

    To protect your business from malicious IP scraping or attacks, configure an IP blacklist/whitelist to filter requests by source IP address at CDN points of presence (POPs). A blacklist blocks known malicious IP addresses, while a whitelist allows only trusted traffic. This protects your origin server from attacks.

    Use cases

    Configuration

    Use case

    IP whitelist

    • Protect sensitive internal data: Allow access only from specified IP addresses to sensitive data, ensuring its security.

    • Integrate with third-party services: Ensure that only trusted third-party service IP addresses can access your CDN resources.

    IP blacklist

    • Prevent malicious attacks: If you detect an IP address frequently sending abnormal requests, add it to the blacklist to block its access.

    • Restrict access by region: Block IP address ranges from high-risk regions or countries to comply with certain policies.

    Billing

    The IP Blacklist or Whitelist feature is free of charge. However, blocked requests still incur minor fees. Since the block occurs after the request is processed by the CDN POP (Layer 7), the associated traffic and requests are still billable:

    • Data transfer: A blocked request generates traffic for one request (including the HTTP header) and one response (a 403 page). This traffic is billed as standard CDN data transfer.

    • HTTPS requests: If the domain uses the HTTPS protocol, the TLS handshake is completed before the IP is blocked. Therefore, each blocked HTTPS request is still counted and billed as one HTTPS request.

    Before you begin

    • A domain name can have only one IP blacklist or one IP whitelist rule. The two are mutually exclusive.

    • After you configure an IP blacklist, requests from blocked IPs are rejected with a 403 status code at the CDN POPs, but they are still recorded in your CDN logs. This is expected behavior and confirms that the blacklist is working correctly.

    • A few Internet Service Providers (ISPs) may assign private IP addresses to end users in certain regions. As a result, POPs receive the user's private IP address.

      Note

      Private IP addresses are:

      • Class A: 10.0.0.0 to 10.255.255.255. Subnet mask: 10.0.0.0/8.

      • Class B: 172.16.0.0 to 172.31.255.255. Subnet mask: 172.16.0.0/12.

      • Class C: 192.168.0.0 to 192.168.255.255. Subnet mask: 192.168.0.0/16.

    Procedure

    1. Log on to the Alibaba Cloud CDN console.

    2. On the Domain Names page, find the domain name that you want to manage and click Manage in the Actions column.

    3. In the left navigation tree of the domain name, click Access Control.

    4. In the IP Blacklist or Whitelist section, click Modify.

    5. Use the examples below for a quick setup. You can also refer to the Parameter description to add a configuration.

      • Example 1: Protect the management console (Whitelist + Rules 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.

          • Rules: Enter 203.x.x.10 and 203.x.x.11 (separate by a line feed).

          • Advanced Configuration - IP Rules: Select Determine based on the IP address that is used to connect to the POP.

          • Advanced Configuration - Rule Condition: On the Rules Engine page, configure a rule where the URI contains /admin/* (case-insensitive). Then, select this rule in the Rule Condition section.

            image

        • Result: Only requests from these two IP addresses can access the /admin/ directory. All other requests to this directory will be 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. Rules: Enter FC00:0AA3:0000:0000:0000:0000:0000:0000/48.

          3. Advanced Configuration - IP Rules: Select Determine based on the IP address that is used to connect to the POP.

        • Result: Only requests from this IPv6 CIDR block can access your domain name resources.

      • Example 3: Block an attack source (Blacklist)

        • Goal: A CC attack is detected from the 198.x.x.0/24 network segment and must be blocked immediately.

        • Configuration:

          1. Type: Select Blacklist.

          2. Rules: Enter 198.x.x.0/24.

          3. Advanced Configuration - IP Rules: Select Determine based on the IP address that is used to connect to the POP.

        • Result: All IP requests from the 198.x.x.0/24 CIDR block are rejected by CDN POPs.

    Parameter description

    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.

    Rules

    Rule format requirements

    • When entering multiple IP addresses or ranges, separate them with line breaks.

    • Supports IP addresses or CIDR blocks. IPv4 examples:

      • IPv4 address example: 192.168.0.1.

      • IPv4 CIDR block example: 192.168.0.0/24.

      • You cannot use 0.0.0.0/0 to specify all IPv4 addresses. To specify all IPv4 addresses, use the following subnets:

        • 0.0.0.0/1

        • 128.0.0.0/1

    • IPv6 examples:

      • IPv6 address example: FC00:AA3:0:23:3:300:300A:1234.

      • IPv6 CIDR block example: FC00:0AA3:0000:0000:0000:0000:0000:0000/48.

      • The letters in IPv6 addresses are not case-sensitive. Examples: FC00:AA3:0:23:3:300:300A:1234 and fc00:0aa3:0000:0023:0003:0300:300a:1234.

      • The abbreviated format : : is not supported. For example, FC00:0AA3::0023:0003:0300:300A:1234 is not supported.

      • You cannot use 0000:0000:0000:0000:0000:0000:0000:0000/0 to specify all IPv6 addresses. To specify all IPv6 addresses, use the following subnets:

        • 0000:0000:0000:0000:0000:0000:0000:0000/1

        • 8000:0000:0000:0000:0000:0000:0000:0000/1

    Rule length limit

    The rule list is limited to 30 KB. Depending on the average length of the IP addresses or ranges, you can configure approximately 700 IPv6 addresses/ranges or 2,000 IPv4 addresses/ranges. To block more IPs than this limit allows, activate Edge Security Acceleration (ESA), which supports massive IP blocking and regional blocking. For more information, see Upgrade from CDN or DCDN to ESA and Configure IP access rules.

    IP Rules

    Choose one of the following three rules:

    • Determine based on the XFF header (default)

      This rule is recommended when clients access 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

      This rule is recommended when clients connect directly to the CDN without an intermediate proxy, or when you want to control access based on the proxy server's IP address.

    • Determine based on the XFF header and the IP address that is used to connect to the POP

      This rule is recommended for mixed network environments where some users connect directly and others connect through a proxy.

    Rule Condition

    Rule conditions can identify parameters in a request to determine whether a configuration applies to the request.

    • Do not use conditions

    • If you want to add or edit rules conditions, see Rules engine.

    Reference: How Alibaba Cloud CDN identifies client IP addresses

    CDN POPs can identify client IP addresses in two ways. Each method has its advantages and disadvantages:

    • Real connection IP address (TCP connection IP)

      • Definition: The IP address used by the client to establish a TCP connection with the CDN POP.

      • Advantage: Cannot be spoofed, providing the highest level of security.

      • Disadvantage: When a user accesses through a proxy (such as a corporate network gateway or NAT device), this IP address is the proxy server's, not the client's.

    • X-Forwarded-For (XFF) request header

      • Definition: An HTTP header field used to record the IP address of each proxy server a request passes through. The CDN typically uses the leftmost IP in this header as the client IP.

      • Advantage: Can bypass proxies to get the client's real IP address.

      • Disadvantage: A client can easily forge this header, posing a significant security risk. Malicious users can bypass IP-based access controls by spoofing the XFF header.

    When a client accesses CDN directly, these two IP addresses are the same. However, if the client accesses CDN through a proxy server, the IP addresses are different. For example, if the originating IP address of the client is 10.10.10.10 and the IP address of the proxy server is 192.168.0.1, then:

    • The value of the X-Forwarded-For header might be 10.10.10.10, 192.168.0.1.

    • The originating IP address of the client is 10.10.10.10.

    • The TCP connection IP address is 192.168.0.1.

    To balance security and business flexibility, CDN provides three verification modes based on these IP identification methods.

    IP address validation mode

    Use case

    How it works

    Security

    Determine based on the XFF header (Default)

    Clients access through a trusted proxy that correctly sets the XFF header.

    Extracts and matches only the leftmost IP address in the X-Forwarded-For request header.

    Low. Clients can forge the X-Forwarded-For request header. Malicious users can easily bypass blacklist restrictions.

    Determine based on the IP address that is used to connect to the POP

    Clients connect directly to the CDN without a proxy, or you want to control access based on proxy server IPs.

    Matches only the IP address used to establish the TCP connection between the client and the CDN POP.

    High. The TCP Connection IP cannot be spoofed, providing the most reliable protection.

    Determine based on the XFF header and the IP address that is used to connect to the POP

    Mixed network environments where some users connect directly and others use a proxy.

    Blacklist: The request is blocked if either the IP in the X-Forwarded-For header or the TCP Connection IP matches a rule. Whitelist: The request is allowed if either the IP in the X-Forwarded-For header or the TCP Connection IP matches a rule.

    Medium to high. This mode balances flexibility with security, making it a robust choice for most scenarios.

    FAQ

    Related API operations

    Add an IP Blacklist or Whitelist configuration

    Call the BatchSetCdnDomainConfig operation to configure an IP Blacklist/Whitelist. For parameters details, see Configure IP Whitelist and Configure IP Blacklist.

    Update an IP Blacklist or Whitelist configuration

    Call the BatchSetCdnDomainConfig operation to update the IP Blacklist or Whitelist. For more information about the related parameters, see Configure IP Whitelist and Configure IP Blacklist.

    Important

    This operation updates only the parameters included in the request. For example, if you pass the ip_list parameter but not the ip_acl_xfwd parameter, ip_acl_xfwd will not be updated.

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

    To change the configuration type, for example, from an IP blacklist to an IP whitelist, you must perform the following steps:

    • Call the delete operation to remove the existing IP blacklist configuration.

    • Call the add operation to add the new IP whitelist configuration.

    Delete an IP Blacklist or Whitelist configuration

    Step 1: Query the ConfigId

    Call the DescribeDomainConfigs operation to query the ConfigId of the configuration. If you already know the ConfigId, skip this step.

    Step 2: Delete the configuration

    Call the BatchSetCdnDomainConfig operation and use the ConfigId to delete the configuration.