Control Access Using Custom Request Headers
Last update：2024-07-17 17:29:21
Custom header blacklists and whitelists allow you to define specific HTTP headers that requests to your content on CDN must match. This mechanism ensures that access is granted only to requests from authorized headers or those with particular header values, effectively blocking hotlinking and safeguarding your valuable content.
How to Set Up a Custom Header Blacklist or Whitelist
- Log in to the CDNetworks Console and select the appropriate product.
- Go to the Configuration, locate the domain you wish to configure, and click Edit Configuration
![[Feature Upgrade] Advanced Access Control](https://documents.cdnetworks.com/wcs/draft/help_doc/zh_cn/17/31790/1714283913583_image.png)
. - Navigate to Hotlinking Protection - Customized Header Anti-Hotlinking in the left sidebar and click Add.
- Configure the settings as follows based on your needs.
Effective Range
This defines the range of requests that Custom Header Blacklist or Whitelist will apply to. You can choose from the following options:
| Setting | Description |
|---|---|
| All Requests | The access control rule applies to all types of requests. |
| Only Homepage | Applies only to the root directory of the domain, such as http://domain/ or https://domain/. |
| Specified File Type | Applies only to specific types of files. You can select from the predefined file types on the left or define custom file types. Separate multiple custom types with a semicolon ;.(e.g., jpg;png). |
| Specified URI | Applies only to requests for content at a specific URI. Two URI matching options are available:Exact matching: Complete URI, including parameters.(e.g., path/index.html?abc=123). Ignore the parameter matching: URI without query parameters.(e.g., path/index.html). |
| Specified Directory | Applies to requests under specific directories. For example, /file/abc/ applies to all content under http://domain/file/abc/*.Note: Directories must start and end with /, and can only contain letters, numbers, and certain special characters (underscore, hyphen, percent sign, dot). Multiple directories are supposed to be seperated with line breaks. |
| URL Pattern | Uses regular expressions to control the range of requests that the rules will be applied to. For example, the pattern *.jpg$ ensures that access control applies to all URLs ending with .jpg. |
Header Type
You can configure the custom header blacklist or whitelist according to specific needs.
| Configuration | Description |
|---|---|
| Blacklist | When setting up a blacklist, you need to specify the custom request headers and their corresponding values that are not allowed:Header Blacklist: This is the name of the custom HTTP request header that needs to be validated. Please note that each blacklist can only include one header name.Header Value Blacklist: These are the forbidden header values. If these values are present in the request, access will be denied. You can set multiple prohibited values, separated by ;. |
| Whitelist | When setting up a whitelist, just like the blacklist, you need to specify the custom request headers and their corresponding values that are allowed:Header Whitelist: This is the name of the custom HTTP request header that needs to be validated. Similarly, each whitelist can only include one header name.Header Value Whitelist: These are the permitted header values. Access is only allowed if these values are present in the request. You can set multiple allowed values, separated by ;. |
| Referer | You can determine whether to validate the header originating from the client or the server.Client: Refers to validating specific HTTP headers in requests issued from a client (such as a user’s browser or application) to ensure they meet preset rules.Server: Involves validating specific response headers in content responses from a server (typically the customer’s origin server) to ensure they comply with preset rules. |
The system allows only one custom header whitelist, which can contain only one custom header. If you need to include multiple custom headers, please contact our Customer Service for assistance.
Action
Decide how to handle requests that do not meet the specified rules:
- Deny Access: Returns a 403 error for requests that fail validation.
- Redirect URL: Redirects requests that fail validation to a specified URL.
Ignore Case
You can decide whether the custom header blacklist or whitelist is case-sensitive. If set to Yes, the values in the list will NOT be case-sensitive.
Priority
When multiple access control rules are configured, the CDN prioritizes them based on their numerical value, executing higher numbers first.
After setting up, click Confirm and then Next to submit your configurations. To prevent disruptions to your production environment, we recommend a pre-deployment in a test environment to verify the correctness of your settings. Once verified, click Direct Deployment to apply the settings live, typically taking effect within 3-5 minutes. For more details on pre-deployment testing, please refer to the tutorial on Verifying Configurations Through Pre-Deployment.
Best Practices
Example 1: Configuring a Custom Header Blacklist
Deny access if client requests include the header Test-Header with values key1 or key2.
Example 2: Configuring a Custom Header Whitelist
Allow access only if client requests include the header Test-Header with values key1 or key2.
Notes
Please DO NOT configure both custom header blacklist and whitelist simultaneously, as it may lead to all CDN accesses being denied, impacting your online operations. For instance, if both blacklist and whitelist configurations are set for the same header, it could result in all requests being denied.
Why might all access be denied?
- If a request contains the header
Test-Headerwith valuekey1, it matches the blacklist rule, resulting in denied access. - If a request contains the header
Test-Headerwith a value other thankey1, it won’t be blocked by the blacklist but will fail to meet the whitelist (which allows only theTest-Headerwith value ofkey1), resulting in access being denied.
If you need to configure both a blacklist and a whitelist, please contact our Customer Service for assistance to ensure proper setup.