Access-Control-Expose-Headers: Syntax, Directive, Examples

Access-Control-Expose-Headers is an HTTP response header that determines which headers are to be exposed to the client scripts on a web browser, as a part of a response to a CORS (Cross-Origin Resource Sharing) request. CORS (Cross-Origin Resource Sharing) is an HTTP-header-based mechanism that allows verified access to other resources located outside the domain. The Access-Control-Expose-Headers HTTP response header provides the list of acceptable headers to the web server, except for the CORS-safelists response headers. The CORS-safelists HTTP response headers are exposed by default on the web pages. The CORS-safelist is an HTTP header in a CORS (Cross-Origin Resource Sharing) response that is classified to be safe to expose to the client scripts. In using the pre-CORS, the client can initiate a cross-origin request with a script tag, however, it will not be able to read the response headers. To assure that CORS will not fail to meet the assumption, the CORS spec will require the webserver to provide specific permissions for the client to read the acceptable headers by using the Access-Control-Expose-Headers HTTP response header. Through this approach, malicious or unofficial CORS (Cross-origin Resource Sharing) requests will function as it does on a pre-CORS procedure. A pre-CORS request is also called the CORS preflight request. A CORS (Cross-origin Resource Sharing) preflight request ensures that the protocol is being implemented and the webserver is knowledgeable on the mechanisms and headers.

What is Access-Control-Expose-Headers?

The Access-Control-Expose-Headers HTTP response header shows which headers can be exposed, as part of the response, by displaying the acceptable header names to the client scripts on a web browser. The only HTTP header that does not require the use of the Access-Control-Expose-Headers HTTP response header is the CORS-safelists response header. The CORS-safelists HTTP response headers are the Cache-Control HTTP header, Content-Language HTTP header, Content-Length HTTP header, Content-Type HTTP header, Expires HTTP header, Last-Modified HTTP header, and Pragma HTTP header. On the web pages, the CORS-safelists HTTP response headers are displayed by default. Other HTTP headers can also be included in the CORS-sale listed by using the Access-Control-Expose-Headers HTTP response headers.

What is the Syntax of Access-Control-Expose-Headers?

The syntax for the Access-Control-Expose-Headers HTTP response header is below.

Access-Control-Expose-Headers: [<header-name>[, <header-name>]*]
Access-Control-Expose-Headers: *

Example usage of the Access-Control-Expose-Headers HTTP response header is when we expose a header that is not included on the CORS-safelists. The format of the syntax is shown below.

Access-Control-Expose-Headers: Content-Encoding

What are the Directives of Access-Control-Expose-Headers?

The directives for the Access-Control-Expose-Headers HTTP response header are below.

  • <header-name> Header name refers to a list of acceptable HTTP header names that can be accessed by the clients. The header names are separated by a comma.
  • <*> asterisk is represented as a wildcard. A special wildcard value is used in requests without credentials. The requests without credentials are also known as requests without HTTP cookies or with no HTTP authentication information. The asterisk “*” value on requests with credentials are considered as the literal header name “*” with no special semantics required.

How to use Access-Control-Expose-Headers?

The usage of Access-Control-Expose-Headers HTTP response header is used to show which HTTP header names are approved to expose on client scripts. The Access-Control-Expose-Headers HTTP response header is inserted by using a comma-separated list of HTTP response headers. The Access-Control-Expose-Headers HTTP response header is also used to expose a custom header, we can use the syntax below to show comma-separated multiple headers.

Access-Control-Expose-Headers: Content-Encoding, Last-Modified

For requests with no required credentials, a web server can provide a wildcard value “*” as a response. The syntax of the example is below.

Access-Control-Expose-Headers: *

Examples of Access-Control-Expose-Headers Use

Example usage of the Access-Control-Expose-Headers HTTP response header is for a Cross-domain head request in Javascript. To measure the Content-Length of a download before performing the AJAX request, we need to create a cross-domain head request. Since the Content-Length is not in CORS-safelists, it will not be returned using the Javascript code.

To allow the Content-Length to be read by the client, we will need to use the Access-Control-Expose-Headers HTTP response header to add the Content-length HTTP header. We can use the syntax below to expose the Content-length HTTP header by using the Access-Control-Expose-Headers HTTP response header.

Access-Control-Expose-Headers: content-length

What are the Specification Documents for Access-Control-Expose-Headers?

The specification documents for the Access-Control-Expose-Headers HTTP response header are RFC2616 and RFC7230. The definitions of the RFC specifications for the related HTTP headers are below.

  • RFC2616: The RFC2616 defines the standard array of HTTP header fields, including Access-Control-Expose-Headers HTTP response headers. 
  • RFC7230: The RFC7230 is a request/response protocol with extensible semantics and self-explained message payloads. The RFC7230 specification document is also known as Message Syntax and Routing.

What are the similar HTTP Headers to the Access-Control-Expose-Headers?

The related HTTP headers for Access-Control-Expose-Headers HTTP response header are  Content-Encoding HTTP header, Content-Language HTTP header, and Content-Length HTTP header. The Access-Control-Expose-Headers HTTP response header is used to indicate the Content-Encoding HTTP header, Content-Language HTTP header, and Content-Length HTTP header on the client scripts since these HTTP headers are not included in the CORS-safelists. The definition of the similar HTTP headers for the Access-Control-Expose-Headers HTTP response header is below.

  • Content-Encoding HTTP response header is used by a web server to notify a client of the selected proposal.
  • Content-Language HTTP header is used to define the languages intended for the user agent.
  • Content-Length HTTP header is used to notify the web server and client of the size of the request and response body that is being transmitted.
Koray Tuğberk GÜBÜR

Leave a Comment

Access-Control-Expose-Headers: Syntax, Directive, Examples

by Koray Tuğberk GÜBÜR time to read: 4 min
0