Configure cross-origin resource sharing

What is cross-origin resource sharing?

Cross-origin resource sharing (CORS) is a standard mechanism that allows a web page to access resources from a different origin (domain, protocol, or port) than its own. It provides a secure way to enable cross-origin data transfers. For more information, see Cross-Origin Resource Sharing (CORS).

Benefits of CORS

Due to security restrictions, browsers typically follow the same-origin policy, which restricts requests to load and access resources from different domains, subdomains, protocols, or ports. For example, example.com cannot access resources on example.org. By configuring cross-origin resource sharing (CORS), you can set relevant response headers on the CDN server. If a request includes headers that meet the allowed rules, the server returns the corresponding HTTP response headers, which allows cross-origin resources to be loaded and accessed.

How it works

CORS configured on the origin server

1. The client sends a request to example.com, for example, https://example.com/index.html.

2. example.com responds with the file index.html. The page contains a link to a resource on a different origin: https://example.org/image_01.png.

3. The client sends a request to example.org.

4. After receiving the request, example.org responds with a cross-origin header, for example, Access-Control-Allow-Origin: *.

5. After receiving the response, the browser checks the value of the cross-origin response header. Because the value is *, which permits access from any origin, the browser renders the response.

With CORS configured on CDN

1. The client sends a request to CDN, for example, https://example.com/index.html.

2. CDN responds with the file index.html, which contains a resource from another origin: https://example.org/image_01.png.

3. The client sends a request to CDN: https://example.org/image_01.png. The request includes the header Origin: http://example.com.

4. After receiving the request, CDN checks whether the value of the Origin header matches the Access-Control-Allow-Origin value configured on CDN. Both exact matching (a single value or multiple values) and wildcard domain matching are supported. If the values do not match, CDN does not return a cross-origin header; the header is returned only when a match is found.

5. CDN returns the cross-origin header based on the validation result, for example, Access-Control-Allow-Origin: http://example.com.

6. After receiving the response, the browser checks the value of the cross-origin response header. Because the value is http://example.com, which permits cross-origin access, the browser renders the response.

Usage notes

• If you use an OSS bucket as the origin server, the CORS configuration in the CDN console overrides the CORS configuration in the OSS console. For more information about how to configure CORS in the OSS console, see Set CORS rules.

• If you use an on-premises server or an ECS instance as the origin server, we recommend that you separate static and dynamic content and use CDN to accelerate the delivery of static files. The CORS feature configured in the CDN console applies only to static files.

Enable cross-origin resource sharing

1. Log on to the CDN console.

2. In the left navigation pane, click Domain Names.

3. On the Domains page, find the domain that you want to manage and click Actions in the Manage column.

4. Click Cache, select the Modify Outgoing Response Header tab, and set the allowed sources and methods for cross-origin requests.

   • Set the origin for cross-origin requests

     Click Customize, configure the parameters as described in the following table, and then click OK.

     Parameter	Description	Example
     Operation	Set this parameter to Add to enable the CORS validation feature.	Add
     Response Header	You must set Access-Control-Allow-Origin to use the cross-origin validation feature.	Access-Control-Allow-Origin
     Header Value	If CORS validation is disabled: You can specify only a wildcard or a single origin. Wildcard *: Allows any origin to access the resource. Single origin: Allows resources to be accessed only from a specific origin (domain name). If CORS validation is enabled: You can specify a wildcard, a single origin, multiple origins, or a wildcard domain. Wildcard *: Allows any source to access the resource. Single origin: Allows resources to be accessed only from a specific origin (domain name). Multiple specified origins: Configure multiple specific origins (domain names), separated by a comma ,, to allow these origins to access the resource. Important When you specify multiple origins, you must separate them with commas (,). If you use semicolons (;) instead, the CORS configuration does not take effect. The console still shows the configuration as successful, but CDN treats the entire semicolon-separated string as a single origin. This origin matches no individual domain in the request, so CORS does not work. Wildcard domain: Specify a wildcard domain to allow access from all origins that match the pattern.	* http://www.aliyun.com https://aliyun.com,http://www.aliyun.com http://*.aliyun.com
     Allow Duplicates	Yes: Headers from the origin server are preserved, and the new, identically named header is also added to the response. No: The new header replaces any identically named header from the origin server. Important The Allow Duplicates and CORS Validation settings are mutually exclusive. If you set Allow Duplicates to Yes, CORS validation is disabled.	No
     CORS	CORS can be configured only when Operation is set to Add, and Response Header is set to "Access-Control-Allow-Origin". CORS can be set to Disable or Enable. The default value is Disable. Disable: CDN POPs do not validate the Origin header in incoming requests and always return the configured Access-Control-Allow-Origin value. Enable: CDN POPs validate cross-origin requests based on the following rules and respond with the Access-Control-Allow-Origin value accordingly. Response Header: If Response Header is set to *, the POP always returns Access-Control-Allow-Origin:*, regardless of whether the user request contains an Origin header or its value. Response Header: Response Header is set to one or more specific origins, separated by commas (,). If the Origin header value in the user request exactly matches one of the configured origins, the POP responds with that origin as the Access-Control-Allow-Origin header value. If no match is found, the POP does not add the CORS header to the response. Response Header: If Response Header is set to a wildcard domain, the POP checks if the Origin header in the request matches the wildcard pattern. If you set Enable to Header Value and the domain name in the Header Value field contains a hyphen (-), you must escape it by replacing - with %-. Example: Original header value: http://doc.aliyun-example.com. Escaped header value: http://doc.aliyun%-example.com.	Enable

   • Set the methods for cross-origin requests

     Click Customize, configure the parameters as described in the following table, and then click OK.

     Parameter	Description	Example
     Operation	Set this parameter to Add.	Add
     Response Header	Must be set to Access-Control-Allow-Methods	Access-Control-Allow-Methods
     Header Value	Supports the GET, POST, and PUT request methods. If you need to add GET, POST, and PUT at the same time, separate them with a comma ,.	GET
     Allow Duplicates	Yes: Headers from the origin server are preserved, and the new, identically named header is also added to the response. No: The new header replaces any identically named header from the origin server.	No

Configuration examples

Verify that the cross-origin configuration is effective

1. The new cross-origin response header does not automatically apply to previously cached resources because CDN caches the complete HTTP response. To apply the new Access-Control-Allow-Origin configuration, you must purge the corresponding resources from the CDN cache. Otherwise, users will continue to receive responses from the old cache that do not include the header.

2. Use curl to send a GET request with a specified Origin header and check the response header in the verbose output: curl -svo /dev/null https://accelerated.domain.name/resource/path -H 'origin:https://your-site.example.com'

3. Check the Access-Control-Allow-Origin header in the response. If the value of the header is * or matches the Origin of the request, the configuration is effective.

Usage notes and limits

For how to troubleshoot cases in which CORS errors persist after you configure Access-Control-Allow-Origin, see Cache troubleshooting.