Object Storage Service:Hotlink protection

How it works

When a browser requests an OSS file, the HTTP Referer header identifies the requesting page. OSS validates this Referer value to verify the request origin.

After hotlink protection is configured, OSS evaluates requests in this order:

1. Empty Referer check: OSS checks whether the Referer is empty. If empty, the following logic applies:

   • If you allow requests with an empty Referer, the request is allowed.

   • If you do not allow requests with an empty Referer and the whitelist is empty, the request is allowed.

   • If you do not allow requests with an empty Referer and the whitelist is not empty, the request is denied.

   If the Referer is not empty, the check proceeds to the next step.

2. Blacklist check: OSS checks whether the Referer matches any blacklist entry. A match results in immediate denial — the whitelist is not checked. Otherwise, processing continues.

3. Whitelist check: OSS checks whether the Referer matches any whitelist entry. A match allows the request; no match denies it.

Procedure

1. Go to the Buckets list and click the target bucket.

2. In the left navigation pane, choose Content Security > Hotlink Protection. Enable the Hotlink Protection option and configure the Referer rules as needed:

   • Referer Whitelist: Domains allowed to access your resources. Enter one per line.

   • Referer Blacklist: Domains denied access. Enter one per line. Blacklist takes priority over the whitelist.

   • Allow Empty Referer: Whether to allow requests without a Referer header, such as direct browser access.

   • Truncate QueryString: Whether to ignore the query string after ? in the URL during matching. Query string parsing rules.

   Referer rules support wildcards:

   Wildcard	Description	Example
   *	Matches zero or more characters.	*.example.com matches http://www.example.com and https://help.example.com.
   ?	Matches one character.	http://www.aliyun?.com matches http://www.aliyunc.com.

   Referer rules also support domains or IP addresses with ports, such as http://www.example.com:8080 and 10.10.10.10:8080.

   Note

   Matching is protocol-sensitive. A rule for http://www.aliyun.com does not match https://www.aliyun.com. Add entries for both HTTP and HTTPS.

3. Click Save to apply the settings.

Use cases

# Simulate a request from a whitelisted Referer (expected to succeed)
curl -e "http://www.aliyun.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate a request from a non-whitelisted Referer (expected to return AccessDenied)
curl -e "http://www.example.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate a request with an empty Referer (expected to succeed)
curl http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate a request from a normal website (expected to succeed)
curl -e "http://www.example.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate a request from a blacklisted website (expected to return AccessDenied)
curl -e "http://bad-site.example" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate a request with an empty Referer (expected to succeed)
curl http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate a request from a WeChat mini program (expected to succeed)
curl -e "https://servicewechat.com/wx1234567890abcdef/1/page-frame.html" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate a request from another source (expected to return AccessDenied)
curl -e "http://www.example.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate a request with an empty Referer (expected to succeed)
curl http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate access from the console (expected to succeed)
curl -e "https://oss.console.alibabacloud.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate a request from the website (expected to succeed)
curl -e "http://www.example.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate direct access (expected to return AccessDenied)
curl http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

# Simulate a request from another website (expected to return AccessDenied)
curl -e "http://other.example" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

Query string parsing rules

If you disable the Truncate query string option, OSS parses the query string as follows:

Production considerations

• CDN cache bypass risk: Hotlinking requests may hit a CDN edge node and be served from cache, bypassing OSS hotlink protection. To prevent this, also configure the same Referer hotlink protection rules on your CDN.

• Impact of browser Referrer-Policy: Browsers support the Referrer-Policy header, which controls how much Referer information is sent in cross-origin requests. Policies like no-referrer cause the browser to omit the Referer, and OSS treats these as empty-Referer requests. Consider this when configuring rules.

• Video playback compatibility: The browser's native video tag sends an initial request with a Referer and subsequent media data requests with an empty Referer. To ensure video playback works, you must allow access for requests with an empty Referer.

Quotas and limits

• anonymous access or a signed URL. API calls signed with an AccessKey (requests that include an Authorization header) are not restricted by hotlink protection rules.

• List size limit: The combined Referer whitelist and blacklist cannot exceed 20 KB.

• Scope: Hotlink protection applies at the bucket level. Per-object or per-directory rules are not supported.

FAQ