You can configure a Referer whitelist for a bucket in Object Storage Service (OSS) to implement access control on resources in the bucket. This prevents hotlinking by unauthorized parties and the fees that are generated as a result. This topic provides examples on how to configure hotlink protection in the OSS console and describes how to troubleshoot common errors related to hotlink protection.

Details

You can use the OSS console and OSS SDKs to configure hotlink protection for a bucket. For more information about hotlink protection, see Hotlink protection.

Hotlink protection configuration examples

The following examples show you how to configure hotlink protection. help.example.com is used in the examples.

  • Reject requests that have empty Referer fields and configure a Referer whitelist
    Note If you configure OSS to reject requests that have empty Referer fields but maintain an empty Referer whitelist, OSS does not check the Referer field of incoming requests, rendering the hotlink protection configuration invalid. Therefore, you need to configure a Referer whitelist if you configure OSS to reject requests that have empty Referer fields.
    • Configuration:
      On the Hotlink Protection page for the bucket, select No for the Allow Empty Referer option, and add the allowed domain names to the Referer whitelist:
      • To allow domain names that start with http://help.example.com to access the bucket, add http://help.example.com to the Referer whitelist. OSS checks the Referer field by matching the URL prefix. For example, if you add only http://help.example.com/index.html to the Referer whitelist, domain names that do not start with http://help.example.com/index.html, such as http://help.example.com/logo.html, cannot access the bucket.
      • To allow requests from subdomains of http://help.example.com, such as http://example.help.example.com/index.html, add http://*.help.example.com to the Referer whitelist.
    • Expected results:
      • If a request is sent to access http://[$Bucket_URL]/index.html and the Referer field is empty, HTTP 403 status code is returned.
        Note
        • [$Bucket_URL] is the URL of the requested object in the bucket.
        • HTTP 403 status code is returned because the Referer field in the request is empty.
      • OSS allows a request to the bucket from http://help.example.com/logo.html.
      • HTTP 403 status code is returned for a request to the bucket from http://help.example123.com/index.html. The website is not allowed to access resources in the bucket.
      • OSS allows a request to the bucket from http://example.help.example.com/index.html.
        Note If only http://help.example.com is added to the Referer whitelist, HTTP 403 status code is returned for a request to the bucket from a simulated subdomain of http://help.example.com. This is because a simulated subdomain does not start with http://help.example.com.
  • Allow requests that have empty Referer fields and configure a Referer whitelist
    • Configuration:

      On the Hotlink Protection page for the bucket, select Yes for the Allow Empty Referer option, and add the allowed domain names to the Referer whitelist. In this configuration example, the following domain names are added to the Referer whitelist:

      http://help.example.com
http://*.help.example.com
    • Expected results:
      • If a request is sent to access http://[$Bucket_URL]/index.html and the Referer field is empty, the request is allowed.
      • OSS allows a request to the bucket from http://help.example.com/logo.html.
      • HTTP 403 status code is returned for a request to the bucket from http://help.example123.com/index.html. The website is not allowed to access resources in the bucket.
      • OSS allows a request to the bucket from http://example.help.example.com/index.html.

FAQ

If you cannot use a browser to access objects in a bucket for which hotlink protection is configured, check whether the Referer field in the request matches the entry in the whitelist. In Chrome, you can press F12 to open DevTools and then go to the Network tab to check whether the Referer field in the request matches the entry in the whitelist. If they do not match, reconfigure hotlink protection for the bucket based on your business requirements.

Note If a bucket is configured to reject requests that have empty Referer fields and an exception is returned for a request for objects in the bucket, check the returned Referer field and determine whether to add the Referer to the Referer whitelist based on your business requirements.

I configured hotlink protection for a bucket, but I can still access objects in the bucket by using the curl command. How can I fix this issue?

  • Cause: The Referer whitelist does not take effect due to one of the following factors:
    • The access control list (ACL) of the bucket is public read/write.
    • CDN is used to accelerate access to the bucket but no Referers are configured in CDN.
  • Solutions:
    1. Check whether the ACL of the bucket is public read/write. If the ACL is public read/write, we recommend that you change the ACL to private.
    2. Check whether CDN is used to accelerate access to the bucket. If CDN is used, you must configure the same Referers in CDN as the Referers in OSS. For more information about how to configure Referers in CDN, see Configure a referer whitelist or blacklist to enable hotlink protection.
      Note If you use CDN to accelerate access to the bucket, we recommend that you configure the Referers in CDN. If you configure Referers in OSS, a request that includes an allowed Referer in the request headers returns the object to the CDN cache. Subsequent requests for the object succeed even if no Referer is provided in the requests.

What do I do if the error message "You are denied by bucket referer policy" is returned with HTTP 403 status code?

If the hotlink protection configuration of the bucket rejects requests with an empty Referer field, OSS allows only requests to the bucket from a Referer that matches entries in the Referer whitelist. In this case, if you send a request for an object such as an image from a browser but leave the Referer field empty, HTTP 403 status code is returned. You can modify the hotlink protection configuration of the bucket to allow requests that have empty Referer fields based on your business requirements.

I added *.example.com and example.com to the Referer whitelist, but a request to the bucket from example.com is rejected. How can I fix this issue?

The URLs that you add to the Referer whitelist must include the http or https scheme. Check the value of the Referer field in the request. For example, if you use Chrome, open DevTools and go to the Network tab to check the value of the Referer field. If no scheme is included, add http:// or https://.

Why does my hotlink protection configuration fail to produce expected results?

The value of the Referer field in your request does not match any entry in the Referer whitelist configured for the bucket. Check the Referer field in the request headers in your browser. In Chrome, you can press F12 to open DevTools and then go to the Network tab to check whether the Referer field in the request matches the entry in the whitelist.

Additional information

Referer

OSS uses Referer to implement hotlink protection. This section provides detailed information about Referer.

  • Definition

    Referer is an HTTP header field that identifies the address of the website from which the resource request originates.

  • Applications
    • Hotlink protection: For example, when a website accesses its own image server, the image server checks the Referer field to determine whether the domain name from which the request originates is allowed. If the domain name is not allowed, the request is rejected.
    • Statistics: For example, you can collect statistics on addresses of webpages that are linked to the resource requested.
  • Empty Referer

    An empty Referer indicates that the Referer field in the HTTP request is empty or the Referer header is not included in the HTTP request. The Referer field is considered as empty under one of the following conditions:

    • The resource request is not initiated by clicking a link. For example, you enter the URL of a resource in the address bar in a browser to access the resource.
    • A link in an HTTPS page is clicked to access a non-encrypted HTTP page.

Hotlink protection configuration considerations

Take note of the following items when you configure hotlink protection for a bucket in OSS:

  • Configuration items
    • Specify whether to allow an empty Referer.
    • Configure a Referer whitelist.
  • Usage notes
    • 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 Authorization field is included in the request.
    • OSS allows you to add multiple domain names to the Referer whitelist. These domain names are separated by commas (,).
    • A value of the Referer field can include asterisks (*) and question marks (?) as wildcards.
    • You can configure whether a 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 requests.
    • If the Referer whitelist is specified and requests with an empty Referer field are rejected, 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 requests with an empty Referer field are allowed, OSS allows requests whose Referer fields are left empty and requests whose Referer fields are included in the Referer whitelist, 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 (*): replaces 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 (?): replaces one character. For example, you can enter love? to search for all objects whose names start with love and are five characters in length, such as lovey and lovei. To narrow down the search scope, you can enter love?.doc to search for all .doc objects whose names start with love and are five characters in length, such as lovey.doc and loveh.doc.
  • Typical configuration examples
    • Allow all requests to bucket.
      • Allow Empty Referer: Select Yes for Allow Empty Referer.
      • Referer Whitelist: Leave it empty.
    • Only allow requests with specified Referer fields or requests without Referer fields.
      • Allow Empty Referer: Select Yes for Allow Empty Referer.
      • Referer Whitelist: Add http://*.oss-cn-beijing.aliyuncs.com and http://*.aliyun.com to the Referer whitelist.