CORS checking on the CDN side

When a user requests your content from another website, their browser might block such a request, preventing the user from receiving the content. The CORS mechanism, using Access-Control-* headers, allows the browser to pass the request so the user gets the content. For more details, see the example in the section CORS workflow example.

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

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

If you add custom HTTP headers to the response to the user, they are added to the response after the CORS check. If a custom header and a header specified in CORS match, the value of the custom header will be shown in the response to the user. For example, for the header Access-Control-Allow-Origin, CORS is set to example.com, and the custom header value is *. After the CORS check, the response to the browser will contain the header Access-Control-Allow-Origin:*.

CORS checking example

For example, a user on not-my-site.com 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 the Origin header, which specifies the request source (in this example, Origin: not-my-site.com).

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

if the domain is allowed, the server sends the Access-Control-Allow-Origin: not-my-site.com header in the response to the browser, which allows the browser to display the image to the user of not-my-site.com.
if the domain is not allowed, the server does not send the Access-Control-Allow-Origin header in the response to the browser. The browser blocks the request and does 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);
select allowed HTTP methods;
add the Access-Control-Allow-Credentials header;
add the Access-Control-Allow-Origin header to all responses;
specify preflight request caching time.

Add allowed domains

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

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

A request from a domain that is not on the allowed list 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, in the top menu, click Products and select CDN.
In the CDN resources section, open the resource page → Headers tab.
Make sure that in the CDN-side CORS check block, the Enable CORS settings checkbox is selected.
Specify the allowed domain to which the setting applies. Enter the domain without a protocol, for example example.com. You can use:
- example.com — exact match;
- *.example.com — all subdomains of the main domain, excluding the main domain itself. 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 specify 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 the settings are being applied, the resource will have the PROCESSING status. Applying other settings is unavailable at this time. The settings will apply once the resource changes its status 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 additional headers. The response to the browser will contain the Access-Control-Allow-Headers: <allowed_header> header, where <allowed_header> is the name of the allowed header.

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

In the Control panel, in the top menu, click Products and select CDN.
In the CDN resources section, open the resource page → Headers tab.
Make sure that in the CDN-side CORS check block, the Enable CORS settings checkbox is selected.
In the Safe request headers list, enter the header and click . The header will be added to the allowed list.
Optional: in the Safe 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 allowed list.
Click Apply. While the settings are being applied, the resource will have the PROCESSING status. Applying other settings is unavailable at this time. The settings will apply once the resource changes its status 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 additional headers. The response to the browser will contain the Access-Control-Expose-Headers: <expose_header> header, where <expose_header> is the name of the allowed header.

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

In the Control panel, in the top menu, click Products and select CDN.
In the CDN resources section, open the resource page → Headers tab.
Make sure that in the Headers available to top-level API (Expose Headers) block, the Enable CORS settings checkbox is selected.
In the Safe request headers list, enter the header and click . The header will be added to the allowed list.
Optional: in the Headers available to top-level API (Expose Headers) list, select headers if you have already added them.
Click Apply. While the settings are being applied, the resource will have the PROCESSING status. Applying other settings is unavailable at this time. The settings will apply once the resource changes its status 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.

By default, the following methods are allowed: GET, HEAD, POST, OPTIONS. They cannot be disabled.

You can additionally select allowed methods. The response to the browser will contain the Access-Control-Allow-Methods:<allowed_method> header, where <allowed_header> is the name of the allowed method.

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

In the Control panel, in the top menu, click Products and select CDN.
In the CDN resources section, open the resource page → Headers tab.
Make sure that in the CDN-side CORS check block, the Enable CORS settings checkbox is selected.
In the Safe methods list, select the methods you want to allow:
- PUT;
- PATCH;
- DELETE;
- OPTIONS.
Click Apply. While the settings are being applied, the resource will have the PROCESSING status. Applying other settings is unavailable at this time. The settings will apply once the resource changes its status to ACTIVE.

Add the Access-Control-Allow-Credentials header

When this option is enabled, the CDN adds the Access-Control-Allow-Credentials: true header to the response, which allows sending cookies and authentication credentials. The header is added to the response only if the request passed CORS checking.

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, in the top menu, click Products and select CDN.
In the CDN resources section, open the resource page → Headers tab.
Make sure that in the CDN-side CORS check block, the Enable CORS settings checkbox is selected.
Select the Access-Control-Allow-Credentials header checkbox.
Click Apply. While the settings are being applied, the resource will have the PROCESSING status. Applying other settings is unavailable at this time. The settings will apply once the resource changes its status 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, including responses with an error status. This allows handling failed requests.

In the Control panel, in the top menu, click Products and select CDN.
In the CDN resources section, open the resource page → Headers tab.
Make sure that in the CDN-side CORS check block, the Enable CORS settings checkbox is selected.
Select the Access-Control-Allow-Origin header always checkbox.
Click Apply. While the settings are being applied, the resource will have the PROCESSING status. Applying other settings is unavailable at this time. The settings will apply once the resource changes its status to ACTIVE.

Specify the caching time for the Preflight response

A preflight request is an initial request using the OPTIONS method sent prior to the actual request. Its purpose is to verify in advance that the request is allowed. The actual request is sent only after the preflight check succeeds.

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 cache time is passed in the Access-Control-Max-Age header.

In the Control panel, in the top menu, click Products and select CDN.
In the CDN resources section, open the CDN resource page → Headers tab.
Make sure that in the CDN-side CORS check block, the Enable CORS settings checkbox is selected.
In the Preflight request response lifetime field, specify the value in seconds. The higher the value, the less frequently the browser sends preflight requests.
Click Apply. While the settings are being applied, the CDN resource will have the PROCESSING status. Applying other settings is unavailable at this time. The settings will apply once the CDN resource changes its status to ACTIVE.

Disable CORS checking on the CDN side

In the Control panel, in the top menu, click Products and select CDN.
In the CDN resources section, open the CDN resource page → Headers tab.
In the CDN-side CORS check block, clear the Enable CORS settings checkbox.
Click Apply. While the settings are being applied, the CDN resource will have the PROCESSING status. Applying other settings is unavailable at this time. The settings will apply once the CDN resource changes its status to ACTIVE.