Configure cache outbound response headers-CDN(CDN)-阿里云帮助中心

Outbound response headers are one of the components of HTTP response message headers. They can carry specific response parameters and pass the parameters to clients, and can be used to control various types of client behavior, such as cache behavior, cross-origin access, content types, and download methods. By modifying outbound response headers, when users request resources under an accelerated domain name, the response message returned by CDN carries the response headers that you configured, which enables specific features such as cross-origin access.

Background information

Outbound response headers are a mechanism used to control caching in the HTTP protocol. When a client requests a resource, the HTTP response headers returned by the node allow the content to be cached under specific conditions.

Note

The HTTP response header configuration is a domain-level configuration. After the configuration takes effect, it applies to the response messages of all resources under the domain.
Configuring HTTP response headers affects only the response behavior of the client (for example, a browser) and does not affect the caching behavior of CDN nodes.If the accelerated domain name is a wildcard domain name, modifying outbound response headers is not supported.

Scenarios

Inform the client of the resource type ofCDN response files: Add the response header Content-Type: text/html to inform the client that the response files returned by CDN are in the HTML format.
Implement cross-origin resource access: When a user requests resources of a domain name on CDN , you can configure the response header Access-Control-Allow-Origin in the response message returned by CDN to implement cross-origin access. For more information, see Configure cross-origin resource sharing. Alibaba Cloud CDN also supports validating the cross-origin requests received from users based on the configured CORS rules, which provides more flexible control over cross-origin resource access.
File downloads: When you access OSS files through a CDN-accelerated domain name, the browser previews the files by default. Add Content-Disposition: attachment to the outbound response headers to make the browser download the files instead of previewing them.
Customize response behavior: Add or modify custom header information based on business requirements to adjust the content and format of the responses received by clients.

Notes

Multiple configurations are executed from top to bottom in the order they appear in the configuration list. The effects are cumulative. If multiple configurations modify the same header, the last one takes precedence. In the following example, Configuration 2 is the one that takes effect:
- Configuration 1: Add the HTTP response header: cache-control: max-age=3600
- Configuration 2: Add the HTTP response header: cache-control: no-cache
When rule conditions are applied, matching is determined by the priority of the conditions, not the order of the configurations.

CDN does not support deleting or modifying system-reserved response headers, such as Via and EagleId. These headers are used to record information about CDN nodes. Even if you configure deletion or modification, the configuration does not take effect, and the system still retains the information of the last node.
After outbound response header configurations are modified, the configurations generally take effect within 5 minutes. You do not need to prefetch resources again (prefetch does not change the response headers of cached resources).

Procedure

Log on to the CDN console.
In the left navigation pane, click Domain Names.
On the Domain Names page, find the target domain name and click Manage in the Actions column.
In the domain's navigation pane, click Cache.
Click the Modify outbound response headers tab.

Click Customize to modify outbound response headers.

The following example describes how to add an outbound response header.

Parameter	Description
Operation	Add, delete, change, or replace the specified response headers.
Response Header	Select a custom response header parameter. For more information, see Response header parameters.
Header Name	When the custom response header parameter is set to Custom, you must configure a custom response header name. The requirements for custom response header names are as follows: Consists of uppercase letters, lowercase letters, hyphens, and digits. Is 1 to 100 characters in length.
Header Value	Enter the response header value that you want to set. For more information, see Response header parameters.
Allow Duplicates	Yes: Retains the header returned by the origin server and adds a header with the same name. No: The header returned by the origin server is overwritten by the newly configured header with the same name.
CORS	CORS validation is disabled by default. You can configure CORS validation only when Operation is set to "Add" and Response Header is set to "Access-Control-Allow-Origin". Enable: When CORS validation is enabled, CDN nodes validate the cross-origin requests of users based on the following rules and respond with the value of "Access-Control-Allow-Origin" based on the validation result. Disable: When CORS validation is disabled, CDN nodes do not validate the Origin header carried in user requests and respond only with the configured Access-Control-Allow-Origin value. For the CORS validation rules, see CORS validation rules.
Rule Condition	Rule Conditions can identify various parameters carried in user requests to determine whether a configuration takes effect for a request. Important When you reference rule conditions, the system matches rules based on the priority of the associated rule conditions instead of the configuration order of the features. Do not use: Do not use rule conditions. To add or edit rule conditions, manage them in Rules engine.

Click OK to complete the configuration.
After you successfully modify outbound response headers, you can perform Modify or Delete operations on the current configuration in the outbound response header POP HTTP Response Header list.

Configuration example: Configure Cache-Control:no-cache for PDF files

If you want the client to perform cache negotiation on PDF files (verify with CDN nodes whether the files are updated on each request), you can use the rule engine:

When you Customize an outbound response header configuration, select to use Rule Condition.
Set the match condition to file extension contains .pdf.
Configure the action to modify outbound response headers and add cache-control:no-cache.

Important

This configuration affects only the response headers that CDN returns to the client and makes the client perform cache negotiation, but does not affect the caching policy of CDN nodes for the PDF files.

CORS validation rules

Important

The Allow Duplicates and CORS configuration items are mutually exclusive. If Allow Duplicates is set to Yes, CORS validation becomes invalid.

Wildcard match: If the value of the custom response header parameter Access-Control-Allow-Origin is set to *, Access-Control-Allow-Origin:* is always returned, regardless of whether the user request carries the Origin parameter and regardless of the value of the Origin parameter.
Exact match: The value of the custom response header parameter Access-Control-Allow-Origin is set to one or more values (separate multiple values with ,).
- If the value of the Origin parameter carried in the user request header exactly matches any of the configured values, the corresponding cross-origin header is returned.
- If no exact match is found, no cross-origin header is returned.
Wildcard domain match: If the value of the custom response header parameter Access-Control-Allow-Origin is set to a wildcard domain name, the system validates whether the Origin value in the request header matches the wildcard domain name of Access-Control-Allow-Origin.

For information about how to configure the settings, see Configure cross-origin resource sharing.

Response header parameters

Response header parameter	Description	Example
Custom	You can add custom response headers. The requirements for custom response header names are as follows: Consists of uppercase letters, lowercase letters, hyphens, and digits. Is 1 to 100 characters in length.	Test-Header
Cache-Control	Specifies the caching mechanism that the requests and responses of the client program must follow.	no-cache
Content-Disposition	Specifies the default file name provided when the client program saves the content obtained from a request as a file.	examplefile.txt
Content-Type	Specifies the content type of the response object of the client program.	text/plain
Pragma	Pragma is a general header specified in HTTP/1.0. This header is typically used in server responses to define the caching behavior of the client for files.	no-cache
Access-Control-Allow-Origin	`Access-Control-Allow-Origin` is an HTTP response header used to indicate which origins can access resources. It is part of the cross-origin resource sharing (CORS) mechanism, which allows servers to declare whether their resources can be accessed by a specific origin (domain name). The value of this response header supports the following types: Wildcard ``: The wildcard indicates that resources can be accessed from any origin. This method is very permissive and is suitable for public resources that can be accessed without authentication or authorization. However, exercise caution when you use wildcards in production environments because wildcards may pose security risks, such as scripts on malicious sites reading API response data. Single specific origin*: You can specify a specific origin (domain name) to indicate that only the specific origin can access resources. For example, `http://example.com` or `https://api.example.com`. This requires that requests come from the specified origin. Otherwise, the requests are rejected.	* http://www.aliyun.com
Access-Control-Allow-Methods	Specifies the allowed cross-origin request methods. Separate multiple methods with commas (`,`).	POST,GET
Access-Control-Allow-Headers	Specifies the allowed cross-origin request fields.	X-Custom-Header
Access-Control-Expose-Headers	Specifies the custom header information that can be accessed.	Content-Length
Access-Control-Allow-Credentials	Indicates whether the response to a request can be exposed to the page. If true is returned, the response can be exposed. If another value is returned, the response cannot be exposed.	true
Access-Control-Max-Age	Specifies the cache duration of the preflight request result for a specific resource of the client program. Unit: seconds.	600
Content-Security-Policy	Configures a Content Security Policy (CSP) to control which resources a page can load, and defend against security threats such as XSS attacks and data injection. CDN does not perform semantic validation on CSP policy content and validates only the basic format of the HTTP response header. The policy content must be a single-line string and cannot contain line breaks, invalid control characters, or unescaped quotation marks. Do not include the outer double quotation marks. We recommend that you verify the policy in browser developer tools before you enter the policy, or configure the CSP on the origin server so that CDN passes it through.	default-src 'self'; script-src 'self' 'unsafe-inline'
Permissions-Policy	Configures permissions policies to control the access permissions to specific browser features, such as the camera, microphone, and geolocation.	camera=(), microphone=()

Note

The response header value can be set to *, which indicates any origin.
If the response header value is not *, you can configure one or more IP addresses, one or more domain names, or a combination of IP addresses and domain names. Separate them with commas (,).
If the response header value is not *, the value must contain the protocol header http:// or https://.
The response header value can contain ports.
The response header value supports wildcard domain names.

Differences between outbound and inbound response headers

Outbound and inbound response headers apply to different stages of the caching process. Before you configure a response header, confirm the target object:

Outbound response headers (node HTTP response headers): Response headers sent from CDN nodes to clients, such as browsers. If a node has cached content, the node returns the content directly to the client without an origin fetch. This type of response header is used to control the caching behavior between the client and the CDN node.
Inbound response headers (origin fetch HTTP response headers): Response headers sent from the origin server to CDN nodes. When the cache on a node expires or a cache miss occurs, the node requests the latest content from the origin server. The headers returned by the origin server are inbound response headers. This type of response header is used to control the caching behavior between the origin server and the CDN node.

Note

Modifications to inbound response headers (such as modifying the domain field of Set-Cookie) affect only the communication between the origin server and CDN nodes, and end users are not aware of these modifications. To affect the responses that end users receive, configure outbound response headers. If outbound response headers still do not take effect, we recommend that you modify the response headers on the origin server.

Batch configuration for multiple domain names

Outbound response header configurations can be added to multiple domain names in batches. You can call the BatchSetCdnDomainConfig API operation to batch configure domain names, and set the rules for adding response headers by using the function parameters of the operation.

Effective time of configurations

Configurations generally take effect within 5 minutes. Before a configuration takes effect, the status is displayed as Configuring, which is normal.

FAQ

For information about how to troubleshoot issues such as response header configurations that do not take effect, see Cache troubleshooting guide.