All Products
Search
Document Center

CDN:Configure a UA blacklist or whitelist

Last Updated:Jul 29, 2025

The User-Agent is a field in an HTTP request header that contains information about a client, such as its operating system and browser type and version. You can configure a User-Agent blacklist or whitelist to restrict access to CDN resources and improve the security of CDN.

Usage notes

  • The User-Agent blacklist and whitelist are mutually exclusive. You cannot configure both at the same time.

  • If the User-Agent field in a request hits a value in the User-Agent blacklist, the request still reaches the CDN node. However, the CDN node rejects the request and returns an HTTP 403 status code. The request is recorded in CDN logs, and you are charged a small amount for the traffic. If the client accesses resources over HTTPS, you are also charged for the HTTPS requests.

  • You can configure User-Agent blacklist and whitelist rules to restrict access to CDN resources and improve CDN security. When CDN nodes block malicious requests, a small amount of traffic fees are incurred. If a client uses the HTTPS protocol, HTTPS request fees are also incurred because blocking malicious requests consumes the processing resources of CDN nodes.

Procedure

  1. Log on to the Alibaba Cloud CDN console.

  2. In the left-side navigation pane, click Domain Names.

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

  4. In the left-side navigation tree of the domain name, click Access Control.

  5. Click the User-Agent Blacklist/Whitelist tab.

  6. On the User-Agent Blacklist/Whitelist tab, click Modify.

  7. Follow the prompts on the page to configure the Blacklist or Whitelist for User-Agent.

    Parameter

    Description

    Type

    The following types of User-Agent lists are available:

    • Blacklist

      If the User-Agent field in an HTTP request header hits the blacklist, the user cannot access the requested resource, and an HTTP 403 status code is returned.

    • Whitelist

      Only when the User-Agent field in an HTTP request header hits the whitelist can the user access resources under the accelerated domain name.

    Rules

    When you configure User-Agent values, separate multiple values with vertical bars (|). The wildcard character (*) is supported. Example: *curl*|*IE*|*chrome*|*firefox*.

    Note

    • If you want to control access for requests that contain a User-Agent request header with an empty value, you can use the this-is-empty-ua parameter to indicate that the User-Agent value is empty.

      • For a whitelist: If the rule contains this-is-empty-ua, it indicates that requests that contain a User-Agent request header with an empty value are allowed.

      • For a blacklist: If the rule contains this-is-empty-ua, it indicates that requests that contain a User-Agent request header with an empty value are rejected.

    • If you want to control access for requests that do not contain a User-Agent request header, this feature is not supported by the UA blacklist and whitelist. You can implement this using the EdgeScript feature. For more information, see EdgeScript. Alternatively, you can or submit a ticket to request a backend configuration.

    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.

  8. Click OK to finalize the configuration.

Configuration examples

  • Example 1: Whitelist

    Rule: *IE*|*firefox*

    Result: Only requests from Internet Explorer or Firefox can access the requested resources. All other requests are rejected.

  • Example 2: Blacklist

    Rule: *IE*|this-is-empty-ua

    Result: Requests from Internet Explorer or requests that have a User-Agent header with an empty value are rejected.