Overview

This topic describes how to configure hotlink protection and troubleshoot hotlink protection errors.

 

Field description and configuration

What is Referer?

Referer is a field in the HTTP header. It identifies the address of the Webpage that is linked to the resource being requested.

 

Functions of Referer

  • Hotlink protection. For example, when a website accesses its own image server, the image server obtains Referer to determine whether the domain name in the request is allowed. If the domain name is not allowed, the request is rejected.
  • Statistic collection. For example, you can collect statistics on addresses of Webpages that are linked to the resource requested.

 

Allow Empty Referer

  • An empty Referer indicates that the Referer field in the HTTP request is not specified or the Referer header is not included in the HTTP request. The Referer field is considered as empty under either of the following conditions:
    • The resource is not accessed by clicking a link. For example, enter the address in the address bar to access a Webpage.
    • When you access an HTTP Webpage by clicking the link on the HTTPS Webpage, the agent of the HTTP website cannot obtain the Referer field.
  • When you configure hotlink protection, note that the differences of whether the empty Referer field is allowed are as follows:
    • When you set Referer Whitelist, if you turn on Allow Empty Referer, the resource URL can be accessed through the browser by entering the address in the address bar.
    • If your turn off Allow Empty Referer, the resource URL cannot be accessed through the browser.

 

Hotlink protection

OSS uses Referer to implement hotlink protection. Therefore, hotlink protection is abbreviated to Refer or refer.

 

Hotlink protection configuration

Note: For more information about how to configure Referer, see Configure hotlink protection.

OSS allows you to configure hotlink protection for a bucket through the console or by calling the SDK, as instructed in Hotlink protection.

  • To configure hotlink protection, set the following parameters:
    • Allow Empty Referer
    • Referer Whitelist
  • When you configure hotlink protection, note that:
    • Hotlink protection-based verification is required only when you access an object anonymously or by using a signed URL. Hotlink protection-based verification is not required if the request header contains the Authorization field.
    • OSS allows you to add multiple domain names to the Referer whitelist. These domain names are separated by commas (,).
    • The Referer field value can include asterisks (*) and question marks (?) as wildcards.
    • You can configure whether the request that includes the empty Referer field is allowed.
    • If the Referer whitelist is left empty, all requests are allowed regardless of whether the Referer field is left empty in the request.
    • If the Referer whitelist is specified and Allow Empty Referer is turned off, only requests that include domain names added to the Referer whitelist are allowed. Other requests, including the requests that include the empty Referer field are rejected.
    • If the Referer whitelist is specified and Allow Empty Referer is turned on, OSS allows requests whose Referer fields are left empty and requests whose Referer fields are included in the Referer whitelist as required, and rejects all other requests.
    • Hotlink protection-based verification is required when the ACL of a bucket is Private, Public Read, or Public Read/Write.
  • Wildcards
    • Asterisk (*): used to replace zero or multiple characters. If you are looking for an object whose name is prefixed with AEW but have forgotten the remaining part, you can enter AEW* to search for all objects whose names start with AEW, such as AEWT.txt, AEWU.EXE, or AEWI.dll. To narrow down the search scope, you can enter AEW*.txt to search for all .txt objects whose names start with AEW, such as AEWIP.txt and AEWDF.txt.
    • Question mark (?): used to replace one character. For example, you can enter love? to search for all objects whose names start with love and end with one character, such as lovey and lovei. To narrow down the search scope, you can enter love?.doc to search for all .docobjects whose names start with love and end with one character, such as lovey.doc and loveh.doc.
  • Typical configuration items are described as follows:
    • All requests are allowed to access a bucket.

      • Allow Empty Referer: Turn on this feature to allow requests that include empty Referer fields.
      • Referer Whitelist: Leave it empty.
    • Requests with specified Referer fields or requests without Referer fields can access a bucket.

      • Allow Empty Referer: Turn off this feature so that requests exclude empty Referer fields.
      • Referer Whitelist: http://*.oss-cn-beijing.aliyuncs.com and http://*.aliyun.com.

 

Common errors and troubleshooting

Error 1: After hotlink protection is configured for a bucket, you can still obtain video objects from the object by running the curl command

Cause analysis

The possible cause is that CDN is enabled without configuring the Referer field in CDN.

 

Solution
  1. Check whether CDN is enabled. The Referer field of CDN must be specified. The Referer whitelist must be the same as that for OSS.
  2. Before debugging Referer for OSS, eliminate the impact caused by CDN. Debug Referer for OSS and then debug Referer for CDN.

 

Error 2: When the Referer field is incorrectly configured, HTTP status code 403 is displayed and OSS prompts "You are denied by bucket referer policy."

Cause analysis

Possible causes are as follows:

  • The Referer field is empty. The Referer field is not included in the request or the Referer field is not specified.
  • The Referer field value is not within the specified range or the format is invalid.

 

Solution

We recommend that you clear your browser cache before you perform debugging. If the error persists, perform the following steps to resolve the issue:

  • If the Referer field is empty, log on to the OSS console. Select a Bucket. Click the Basic Settings tab. In the Hotlinking Protecting section, set Referer. Note that only the whitelist instead of the blacklist is supported for Referer in OSS.
  • If the Referer field value is not within the specified range or the format is invalid, check whether http:// or https:// is configured and whether the domain name in the request matches the configured Referer. For example, a.aliyun.com and b.aliyun.com can match http://*.aliyun.com or http://?.aliyun.com. domain.com matches http://domain.com instead of http://*.domain.com.
  • Referer-related errors occur when you use OSS for websites and Referer configurations are not proper. You can view the Referer field included in the header through the browser. If you are using Google Chrome, press F12 to access Developer tools On the Network tab, you can view header information of corresponding elements.
  • Errors returned by OSS can be obtained by capturing packets. For example, you can use Wireshark and specify host bucket-name.oss-cn-beijing.aliyuncs.com as the filter to capture packets.

 

References

For more information about how to troubleshoot other errors, see OSS 403.

 

Application scope

  • OSS