When a client sends a request to a web server, it usually includes a User-Agent header that identifies the device and browser from which the request originates. It typically contains information such as the operating system and version, as well as the browser type and version. Therefore, access control can be enforced based on this header. When a CDN edge server receives a client request, it checks the User-Agent field in the HTTP request header and then allows or denies the request according to the configured rules.

User-Agent access rules are suitable for the following scenarios:

• When content should be accessible only from specific browsers, such as allowing access only from Internet Explorer and denying access from Chrome, User-Agent-based access control can be used.
• When accelerated domains should be accessible only from specific clients, such as a dedicated client that includes a specific User-Agent value in its requests, User-Agent access rules can be used.

How to Set Up a User-Agent Access Rule

1. Log in to the Atomile Console and select the appropriate product.
2. Go to Configuration, locate the domain you want to configure, and click Edit Configuration.
3. In the left sidebar, go to Access Control - User-Agent Access List and click Add.
4. Configure the settings according to your requirements.

Effective Range

This defines the range of requests to which the User-Agent rule applies. You can choose from the following options:

Setting	Description
All Requests	The access control rule applies to all request types.
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 file types. You can select predefined file types or define custom file types. Separate multiple custom types with a semicolon ;, for example, jpg;png.
Specified URI	Applies only to requests for content at a specific URI. Two URI matching options are available: Exact matching: Matches the complete URI, including query parameters, for example, path/index.html?abc=123. Ignore parameter matching: Matches the URI without query parameters, for example, 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: Directory paths must start and end with / and can contain only letters, numbers, and certain special characters (underscore, hyphen, percent sign, and period). Separate multiple directories with line breaks.
URL Pattern	Uses regular expressions to define the range of requests to which the rule applies. For example, the pattern .*\.jpg$ ensures that access control applies to all URLs ending with .jpg.

User-Agent Type

You can configure either a User-Agent blacklist or a User-Agent whitelist.

Configuration	Description
User-Agent Blacklist	If the User-Agent in the HTTP request header matches the blacklist, access is denied.
User-Agent Whitelist	Access is allowed only if the User-Agent in the HTTP request header matches the whitelist.

Tips

• Both the User-Agent blacklist and whitelist can contain multiple values, separated by line breaks.
• The system supports only one whitelist rule. If multiple User-Agent values are required, they must all be included in the same whitelist rule.

Action

When the User-Agent does not meet the configured rules and the request is denied by the CDN, choose whether to return an error directly or redirect the request to another URL.

• Deny Access: The CDN rejects the request and returns HTTP status code 403.
• Redirect URL: The CDN redirects the request to a specified URL.

Ignore Case

Determines whether the blacklist or whitelist rules are case-sensitive. If set to Yes, the values in the list are not case-sensitive. For example, if Chrome/123.0.0.0 is allowed in the whitelist, the request is permitted whether the User-Agent is Chrome/123.0.0.0 or chrome/123.0.0.0.

Priority

When multiple access control rules are configured, the CDN applies them based on numerical priority. Higher numbers are evaluated first.

After you complete the configuration, click OK, and then click Next to submit your settings. To minimize potential disruption to your production environment, we strongly recommend performing a Pre-deploy test in a staging environment. This important step helps ensure that your configuration is correct before it goes live.

After you confirm that the settings are correct, click Deploy Now to apply them in the live environment. The configuration typically takes effect within 3 to 5 minutes. For more information about pre-deployment testing and validation, refer to Deploy the Configurations to Staging Environment for Validation.

Notes

Do not configure User-Agent blacklists and whitelists at the same time, as this may cause all CDN access to be denied and disrupt your online services. For example, if both a User-Agent blacklist and whitelist are configured as shown below, all access requests may be denied.

Why Would All Access Be Denied?

1. Access is denied when the request User-Agent contains Chrome/123.0.0.0, because it matches the User-Agent blacklist.
2. Requests without the User-Agent Chrome/123.0.0.0 are not denied by the blacklist, but they still fail the whitelist rule, which allows access only when the User-Agent contains Chrome/123.0.0.0, and are therefore also denied.

If you need to configure both a blacklist and a whitelist, contact Atomile technical support for assistance to ensure the configuration is set up correctly.