Help Center/ Content Delivery Network/ User Guide/ Custom Domain Name Configuration/ Access Control/ Filtering Requests from Specific Referers
Updated on 2025-09-16 GMT+08:00
View PDF

Filtering Requests from Specific Referers

You can set a referer blacklist or whitelist to identify and filter out values of the Referer header in HTTP requests, controlling access sources.

Background

The Referer header identifies the address of the web page from which the resource has been requested. CDN PoPs can use this header to trace and identify the source.

When receiving access requests from users, the CDN PoPs identify and check users against the referer blacklist or whitelist. Only users meeting blacklist and whitelist requirements can access the content. Unqualified users will receive a 403 error response.

Figure 1 How referers work

Precautions

  • This function is disabled by default.
  • Either a referer blacklist or whitelist can be configured.
  • This function sets access control rules based on the Referer header in HTTP requests. When a client request hits the blacklist and is blocked, a small amount of traffic or bandwidth fees are generated. If the service type of the domain name is whole site acceleration, the client request is also charged for the request fees.

Procedure

  1. Log in to the CDN console.
  2. In the navigation pane, choose Domains.
  3. In the domain list, click the target domain name or click Configure in the Operation column.
  4. Click the Access Control tab.
  5. In the Referer Validation area, click Edit.
    Figure 2 Configuring referer validation
  6. Switch on Status to enable this configuration item.
  7. Select a value for Type and set referer parameters based on service requirements. The following table describes the parameters.
    Table 1 Parameters

    Parameter

    Description

    Filling Rule

    Include blank referer

    A blank referer is when the referer field in an HTTP request is left blank or when an HTTP request does not contain the referer field. If this option is selected, such requests will also be accepted (whitelist) or rejected (blacklist).

    NOTE:

    A blank referer indicates that the referer field is left blank or is not included in an HTTP request. The referer field with value null is not a blank referer.

    /

    Referer whitelist
    • If the referer field of an access request matches the whitelist rules, the requester can access the requested content. Otherwise, CDN returns a 403 error response code, indicating that access is forbidden.
    • If Include blank referer is selected and an access request contains a blank referer, the requester can access the requested content.
    • Enter domain names (excluding the protocol, path, and parameters) and IP addresses and separate them by semicolons (;).
    • Wildcard domain names are supported.
    • Enter up to two asterisks (*). They cannot be consecutive or at the end.
    • Domain names and IP addresses with ports are supported. The maximum port number is 65535.
    • Enter up to 500 domain names and IP addresses.

      Example: www.example.com:443;*.test.com;192.168.0.0

      NOTE:

      Domain names with special configurations support only one asterisk (*).

    Referer blacklist
    • If the referer field in an access request matches the blacklist rules, the requester cannot access the requested content, and 403 Forbidden will be returned. Otherwise, the requester can access the requested content.
    • If Include blank referer is selected and an access request contains a blank referer, the access request will be rejected, and 403 Forbidden will be returned.
    • Enter domain names (excluding the protocol, path, and parameters) and IP addresses and separate them by semicolons (;).
    • Do not enter a specific URL, for example, example.com/abc/01.jpg.
    • Wildcard domain names are supported.
    • Enter up to two asterisks (*). They cannot be consecutive or at the end.
    • Domain names and IP addresses with ports are supported. The maximum port number is 65535.
    • Enter up to 500 domain names and IP addresses.

      Example: www.example.com:443;*.test.com;192.168.0.0

      NOTE:

      Domain names with special configurations support only one asterisk (*).
  8. In the Rule text box, enter the domain names.
  9. Click OK.
  10. (Optional) Disable referer validation.
    • Switch off Status to disable referer validation and clear all referer validation settings. You need to set related parameters when enabling this function again.

Verification

After you configure a referer rule, CDN allows or blocks client requests based on the rule. You can run curl commands to check whether the configuration works.

Scenario: Assume that you have configured a referer blacklist to block requests coming from referer example.com and you have disabled Include blank referer.

Expected result: CDN blocks requests containing http://example.com or https://example.com in the referer field, but it accepts other requests.

  1. To test access from the primary domain name, run curl -e http://example.com -I CDN acceleration domain name.

  2. To test access from a sub-domain name, for example, http://abc.example.com, run curl -e http://abc.example.com -I CDN acceleration domain name.

  3. To test access from another domain name, for example, http://axample.com, run curl -e http://axample.com -I CDN acceleration domain name.

  4. To test access with a blank referer, run curl -e " " -I CDN acceleration domain name.

  5. To test access from a domain name without protocol, for example, axample.com, run curl -e axample.com -ICDN acceleration domain name.

Examples

  1. Assume that a referer whitelist www.test.com is configured for the domain name www.example.com and Include blank referer is selected.

    • If user 1 requests the URL https://www.example.com/file.html and the value of the referer field in the request is blank, CDN returns the content.
    • If user 2 requests the URL https://www.example.com/file.html and the value of the referer field in the request is www.test.com, CDN returns the content.
    • If user 3 requests the URL https://www.example.com/file.html and the value of the referer field in the request is www.abc.com, CDN returns a 403 error response code.
  2. Assume that a referer blacklist www.test01.com is configured for the domain name www.example01.com and Include blank referer is selected.

    • If user 1 requests the URL https://www.example01.com/file.html and the value of the referer field in the request is blank, CDN returns a 403 error response code.
    • If user 2 requests the URL https://www.example01.com/file.html and the value of the referer field in the request is www.test01.com, CDN returns a 403 error response code.
    • If user 3 requests the URL https://www.example01.com/file.html and the value of the referer field in the request is www.bcd.com, CDN returns the content.
Parent topic: Access Control