CORS checking on the CDN side

When a user requests your content from another site, the user's browser may block this request, and the user will not receive the content. The CORS mechanism uses Access-Control-* headers to allow the browser to let the request through so the user can receive the content. Learn more in the example in the CORS workflow example.

By default, CORS checking on the CDN side is enabled and applied to all resource files. You can manage CORS parameters.

If CORS checking is configured on the origin server, we recommend disabling CORS checking on the CDN side so that headers can be passed from the origin unchanged.

If you are adding custom HTTP headers to the user response, they will be added to the response after CORS validation. If a custom header and a CORS header have the same name, the custom header value will be displayed in the user response. For example, if Access-Control-Allow-Origin has a value of example.com set in CORS, and the custom header value is *, after CORS validation, the Access-Control-Allow-Origin:*. header will be passed in the response to the browser.

CORS checking example

For example, a user on the not-my-site.com site opens an image located on your site at cdn.my-site.com/image.jpg.

The user's browser sends a request to the domain server cdn.my-site.com/image.jpg with an Origin header, which indicates the request source (in the example — Origin: not-my-site.com).

The domain server cdn.my-site.com checks the content of the Origin header in the request:

if the domain is allowed, the server will pass the Access-Control-Allow-Origin: not-my-site.com header in the response to the browser, which will allow the browser to display the image to the user on the not-my-site.com site.
if the domain is not allowed, the server will not pass the Access-Control-Allow-Origin header in the response to the browser. The browser will block the request and will not display the image to the user.

Manage CORS parameters

You can configure CORS checking parameters:

add allowed domains;
add allowed request headers;
add allowed headers for API (Expose Headers);
choose allowed HTTP methods;
add the Access-Control-Allow-Credentials header;
add the Access-Control-Allow-Origin header to all responses;
specify the caching time for the Preflight response.

Add allowed domains

By default, your content is available from any domain. The Access-Control-Allow-Origin:*. header is passed in the response to the browser.

You can allow access to content for specific domains. The domain from which the request originated will be specified in the response. For example: Access-Control-Allow-Origin: example.com.

A request with a domain not on the allowlist does not receive the Access-Control-Allow-Origin header in the response. The browser blocks the request, and the user does not receive the content.

In the control panel, go to the top menu, click Products, and select CDN.
In the CDN Resources section, open the resource page → Headers.
Ensure that in the CORS checking on the CDN side block, the Enable CORS settings checkbox is selected.
Specify the allowed domain to which the setting applies. Enter the domain without the protocol, for example example.com. You can use:
- example.com — exact match;
- *.example.com — all subdomains of the main domain, excluding the main domain. For example, all subdomains of example.com, excluding example.com;
- .example.com — all third-level subdomains, including the main domain. For example: all subdomains of example.com, including example.com;
- a regular expression to set a complex rule. For example, ~ad+.example.com.
If you need to add multiple allowed domains, click Add domain and repeat step 4.
Click Apply. While settings are being applied, the resource status will be PROCESSING. During this time, you cannot apply other settings. The settings will be applied once the resource status changes to ACTIVE.

Add allowed request headers

To prevent the browser from blocking requests to the origin with custom headers, you can add those custom headers to the allowlist.

The following headers are allowed by default:

Accept;
Accept-Language;
Content-Type;
Content-Language.

You can also add extra headers. In the response to the browser, the Access-Control-Allow-Headers: <allowed_header> header will be passed, where <allowed_header> is the name of the allowed header.

A request with a header not on the allowlist does not receive the Access-Control-Allow-Headers header in the response. The browser blocks the request, and the user does not receive the content.

In the control panel, go to the top menu, click Products, and select CDN.
In the CDN Resources section, open the resource page → Headers.
Ensure that in the CORS checking on the CDN side block, the Enable CORS settings checkbox is selected.
In the Secure Request Headers list, enter the header and click . The header will be added to the allowlist.
Optional: in the Secure Request Headers list, select headers if you have already added them.
If you have not added headers yet, enter the header and click . The header will be added to the allowlist.
Click Apply. While settings are being applied, the resource status will be PROCESSING. During this time, you cannot apply other settings. The settings will be applied once the resource status changes to ACTIVE.

Add allowed headers for API (Expose Headers)

To prevent the browser from blocking requests to the origin with custom headers, you can add those custom headers to the allowlist.

The following headers are allowed by default:

Cache-Control;
Content-Language;
Content-Type;
Expires;
Last-Modified;
Pragma;
Content-Range.

You can also add extra headers. In the response to the browser, the Access-Control-Expose-Headers: <expose_header> header will be passed, where <expose_header> is the name of the allowed header.

A request with a header not on the allowlist does not receive the Access-Control-Expose-Headers header in the response. The browser blocks the request, and the user does not receive the content.

In the control panel, go to the top menu, click Products, and select CDN.
In the CDN Resources section, open the resource page → Headers.
Ensure that in the Expose Headers (CORS headers) block, the Enable CORS settings checkbox is selected.
In the Secure Request Headers list, enter the header and click . The header will be added to the allowlist.
Optional: in the Expose Headers (CORS headers) list, select headers if you have already added them.
Click Apply. While settings are being applied, the resource status will be PROCESSING. During this time, you cannot apply other settings. The settings will be applied once the resource status changes to ACTIVE.

Choose allowed HTTP methods

To prevent the browser from blocking requests to the origin with specific HTTP methods, you can add those methods to the allowlist.

The following methods are allowed by default: GET, HEAD, POST, OPTIONS. They cannot be restricted.

You can additionally choose allowed methods. The Access-Control-Allow-Methods:<allowed_method> header is passed to the browser in the response, where <allowed_method> is the name of the allowed method.

A request with a method not on the allowlist does not receive the Access-Control-Allow-Methods header in the response. The browser blocks the request, and the user does not receive the content.

In the control panel, go to the top menu, click Products, and select CDN.
In the CDN Resources section, open the resource page → Headers.
Ensure that in the CORS checking on the CDN side block, the Enable CORS settings checkbox is selected.
In the Secure Methods list, select the methods you want to allow:
- PUT;
- PATCH;
- DELETE;
- OPTIONS.
Click Apply. While settings are being applied, the resource status will be PROCESSING. During this time, you cannot apply other settings. The settings will be applied once the resource status changes to ACTIVE.

Add the Access-Control-Allow-Credentials header

When this option is enabled, the CDN will add the Access-Control-Allow-Credentials: true header to the response, which allows the transfer of cookies and authorization data. The header is added to the response only if the request has passed CORS validation.

When this header is added, the request is sent directly to the content origin. The CDN does not cache the response to such a request because it contains personal user data.

In the control panel, go to the top menu, click Products, and select CDN.
In the CDN Resources section, open the resource page → Headers.
Ensure that in the CORS checking on the CDN side block, the Enable CORS settings checkbox is selected.
Select the Access-Control-Allow-Credentials header checkbox.
Click Apply. While settings are being applied, the resource status will be PROCESSING. During this time, you cannot apply other settings. The settings will be applied once the resource status changes to ACTIVE.

Add the Access-Control-Allow-Origin header to all responses

When this option is enabled, the CDN will add the Access-Control-Allow-Origin header to every response to a request, including those that return an error. This allows processing requests that ended with an error.

In the control panel, go to the top menu, click Products, and select CDN.
In the CDN Resources section, open the resource page → Headers.
Ensure that in the CORS checking on the CDN side block, the Enable CORS settings checkbox is selected.
Select the Always Access-Control-Allow-Origin header checkbox.
Click Apply. While settings are being applied, the resource status will be PROCESSING. During this time, you cannot apply other settings. The settings will be applied once the resource status changes to ACTIVE.

Specify the caching time for the Preflight response

A Preflight request is a preliminary request using the OPTIONS method, which is sent before the actual request. Its purpose is to verify in advance that the request is allowed. The actual request is sent only after it has been verified by the Preflight request.

By default, the browser sends a Preflight request every time. You can specify the caching time for the Preflight response to speed up content delivery.

The caching time is passed in the Access-Control-Max-Age header.

In the control panel, go to the top menu, click Products, and select CDN.
In the CDN Resources section, open the CDN resource page → Headers.
Ensure that in the CORS checking on the CDN side block, the Enable CORS settings checkbox is selected.
In the Preflight response lifetime field, specify the value in seconds. The higher the value, the less frequently the browser sends Preflight requests.
Click Apply. While settings are being applied, the CDN resource status will be PROCESSING. During this time, you cannot apply other settings. The settings will be applied once the CDN resource status changes to ACTIVE.

Disable CORS checking on the CDN side

In the control panel, go to the top menu, click Products, and select CDN.
In the CDN Resources section, open the CDN resource page → Headers.
In the CORS checking on the CDN side block, clear the Enable CORS settings checkbox.
Click Apply. While settings are being applied, the CDN resource status will be PROCESSING. During this time, you cannot apply other settings. The settings will be applied once the CDN resource status changes to ACTIVE.