Configure CORS for CDN with HTTP response headers-CDN(CDN)-阿里云帮助中心

After you add your service to Alibaba Cloud CDN, you can enable cross-origin access by configuring HTTP response headers on POPs.

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).

Note

By default, CDN does not enable cross-origin resource sharing (CORS). Without this configuration, browsers enforce the same-origin policy and block cross-origin requests, which prevents other websites from loading your resources.

Why configure cross-origin resource sharing?

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

With CORS configured on CDN

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

Log on to the CDN console.
In the left navigation pane, click Domain Names.
On the Domains page, find the domain that you want to manage and click Actions in the Manage column.

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

Example 1

If the response header value for CORS is set to one or more specific origins separated by commas (,):

If the Origin header value in the user's request exactly matches one of the specified origins, the CDN POP responds with the corresponding CORS header.
If no exact match is found, the CORS header is not included in the response.

On CDN/, set: Access-Control-Allow-Origin: http://example.com,https://aliyundoc.com.

The Origin header of the user request is http://example.com, and the CDN Point of Presence (POP) responds with Access-Control-Allow-Origin: http://example.com.
The Origin header in the user request is https://aliyundoc.com, and the CDN node responds with Access-Control-Allow-Origin: https://aliyundoc.com.
The CDN node will not respond to a user request with the Origin header http://aliyundoc.com (due to a protocol mismatch: the user request uses HTTP, while the CDN is configured for HTTPS).
If the Origin header of a request is http://aliyun.com, the CDN POP will not respond (domain mismatch).

Example 2

If the response header value for CORS is set to a wildcard domain, the POP checks if the Origin value in the request header matches the wildcard pattern.

On CDN/, set: Access-Control-Allow-Origin: http://*.aliyundoc.com.

The user request contains the Origin header http://demo.aliyundoc.com, and the CDN POP responds with Access-Control-Allow-Origin: http://demo.aliyundoc.com.
If the Origin header of a request is http://demo.example.com, the CDN POP will not respond because the domain name does not match.
The CDN node does not respond to a user request with the Origin header https://demo.aliyundoc.com because the request uses the HTTPS protocol, but the CDN is configured with the HTTP protocol.

Verify that the cross-domain configuration is effective

The new cross-domain 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.
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'
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

Wildcard domain configuration limits

After you enable CORS validation, you can configure only a single wildcard domain, or multiple exact domains (non-wildcard) separated by commas. You cannot directly separate multiple wildcard domains with commas (such as https://*.example.com,https://*.example.org).

Differences between font files and video files

Font files (such as .ttf and .woff) are always subject to mandatory CORS response header validation by the browser, regardless of how they are loaded. Video files (such as MP4 and WebM) that are loaded through the video tag are not subject to CORS restrictions by default, unless the crossorigin attribute is explicitly added. Therefore, even if videos and fonts are hosted on the same domain, accessing the videos usually does not trigger CORS errors, but accessing the font files does. This is determined by browser specifications.

CORS configuration when CDN accelerates OSS

If you want to pass through the CORS configuration from the origin OSS bucket, make sure that the first request carries an Origin header. This way, CDN can fetch from the origin and cache the Access-Control-Allow-Origin response header returned by OSS. However, the caching mechanism may cause cross-origin issues for subsequent requests that do not carry an Origin header or that carry a different Origin.

Recommended practice: Add CORS-related response headers by using the Configure an outgoing response header feature in Cache Settings in the CDN console, instead of relying on pass-through.

When multiple CDN domains are associated with the same OSS bucket, configuring the CORS rule only once in OSS and letting CDN automatically inherit it is not supported. Because CDN POPs cache response headers and the caching behavior is affected by whether the first request carries an Origin header, you must configure CORS rules separately for each CDN domain in the CDN console.

Handle 403 responses to OPTIONS preflight requests

When Alibaba Cloud CDN accelerates OSS and a browser sends an OPTIONS preflight request, CDN returns 403 by default. You can use an EdgeScript custom policy to intercept OPTIONS requests and return 204 directly, so that preflight requests are not rejected.

Log on to the Alibaba Cloud CDN console and go to Domain Management.
Select the target accelerated domain name.
On the domain configuration page, click EdgeScript custom policy.
On the staging environment tab, click Add rule and add the following rule:
```
if eq($request_method, 'OPTIONS') { exit(204) }
```
Set Priority to 0 and save the rule. After you verify in the staging environment that the OPTIONS request returns 204, publish the rule to the production environment.

Note

EdgeScript strings must use single quotes. Double quotes are not supported.

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