All Products
Search

This Product

    CDN:Configure a User-Agent blacklist or whitelist

    Document Center

    CDN:Configure a User-Agent blacklist or whitelist

    Last Updated:Jan 06, 2026

    The User-Agent is part of the HTTP request header and identifies the client's operating system, browser type, and version. Use User-Agent blacklist/whitelist rules to control access to your resources and improve security.

    Notes

    • You can configure either a User-Agent blacklist or a whitelist, but not both at the same time.

    • If a request's User-Agent header matches a value on the blacklist, the CDN point of presence (POP) denies the request, returns a 403 status code, and logs the request.

    • Blocking a request still consumes CDN POP resources. Therefore, you may incur a small amount of fees for traffic and, if applicable, for HTTPS requests.

    Procedure

    1. Log on to the CDN console.

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

    3. On the Domain Names page, find the target domain name and click Manage in the Actions column.

    4. In the domain's navigation pane, click Access Control.

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

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

    7. Configure a Blacklist or Whitelist for the User-Agent header as prompted.

      Parameter

      Description

      Type

      The following are the User-Agent list types:

      • Blacklist

        If the User-Agent field in an HTTP request header matches a value in the blacklist, the request is rejected and an HTTP 403 status code is returned.

      • Whitelist

        Only requests whose User-Agent field in the HTTP request header matches a value in the whitelist are allowed to access resources on the accelerated domain name.

      Rules

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

      Note

      • To control access for requests that contain an empty User-Agent header, use the this-is-empty-ua parameter to represent an empty User-Agent value.

        • Whitelist: If the rules contain this-is-empty-ua, requests that contain an empty User-Agent header are allowed.

        • Blacklist: If the rules contain this-is-empty-ua, requests that contain an empty User-Agent header are rejected.

      • The User-Agent blacklist and whitelist feature does not support access control for requests that do not contain the User-Agent header. You can use the EdgeScript feature to implement this. For more information, see EdgeScript. Alternatively, or submit a ticket to request a backend configuration.

      Rule Condition

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

      • Do not use: Do not use rule conditions.

      • To add or edit rule conditions, manage them in the Rules Engine.

    8. Click OK.

    Configuration examples

    • Example 1: Use whitelist to allow requests with from IE or Firefox

      Rule: *IE*|*firefox*

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

    • Example 2: Use blacklist to block requests with an empty User-Agent header

      Rule: this-is-empty-ua

      Result: Requests with an empty User-Agent header are rejected.