Pre-flight Check

Edit online

A CORS aware client attempting to make a cross-origin request first issues a pre-flight check to the resource it is attempting to access.

This is an OPTIONS request containing an Origin header populated with the location which is originating the request and an "Access-Control-Request-Method" header indicating which method the real request uses. This request might optionally contain an "Access-Control-Request-Headers" header indicating any headers which is also included in the cross-origin request.

An example pre-flight request:
OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
Access-Control-Request-Method: GET
Access-Control-Request-Headers: X-IBM-HEADER, X-IBM-HEADER-2

A successful pre-flight request results in the web reverse proxy returning an empty response with HTTP status code 204. Additionally, the response contains headers which indicate to the client what is acceptable in is cross-origin requests.

An example pre-flight response:
204 NO CONTENT
Access-Control-Allow-Origin: https://test.ibm.com
Access-Control-Allow-Method: GET
Access-Control-Allow-Headers: X-IBM-HEADER, X-IBM-HEADER-2
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 3600

Pre-flight Check Processing

The web reverse proxy CORS policy includes the following entries related to CORS pre-flight requests:
[cors-policy:<policy-name>]
request-match
allow-origin
allow-credentials
handle-pre-flight
allow-header
allow-method
max-age
Note: The request-match, allow-origin, and allow-credentials entries are also used when processing regular cross-origin requests.

The handle-pre-flight entry controls whether or not the web reverse proxy responds to pre-flight requests. See handle-pre-flight.

When set to false, pre-flight requests are forwarded to the back-end application like a normal request. When set to true, the web reverse proxy performs CORS processing and generates a pre-flight response without contacting the back-end application.

The processing described in Process Common to Pre-Flight Check and Regular Cross-Origin Requests takes place before the processing described that follows.

Evaluating Access-Control-Request-Method

The first step performed by the web reverse proxy when performing a pre-flight check is to evaluate if the method provided in the requests Access-Control-Request-Method header is permitted. The web reverse proxy indicates to clients which methods are permitted using the Access-Control-Request-Method header.

If no methods are configured, the web reverse proxy allows any method and returns the value provided by the client in the Access-Control-Request-Method header.

If any methods are configured, the method is evaluated against the list of configured methods (see allow-method) and list of simple methods (see Simple Methods and Headers) to determine if it is permitted. If the method is permitted, the reverse proxy returns to the client a list of all allowed methods in the Access-Control-Request-Method header.
Note:
  • Method names are compared in a case sensitive manner.
  • Simple methods are only returned when the configured list of allowed methods for the policy is empty.
Request Headers Response from policy containing:

allow-method = PUT

allow-method = PATCH

 Response from policy containing:

allow-method = 

OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
Access-Control-Request-Method: PUT
...
(Configured method)
 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
Access-Control-Allow-Method: 
PUT, PATCH
...
 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
Access-Control-Allow-Method: 
PUT
...
 
OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
Access-Control-Request-Method: DELETE
...
(Method which is not configured)
 CORS Error Response 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
Access-Control-Allow-Method: 
PUT
...
 
OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
Access-Control-Request-Method: GET
...
(Simple method)
 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
Access-Control-Allow-Method: 
PUT, PATCH
...
 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
Access-Control-Allow-Method: 
GET
...
 
OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
...
(No method)
 Forwarded to the back-end, not a pre-flight request Forwarded to the back-end, not a pre-flight request 
OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
Access-Control-Request-Method: Put
...
(Configured method with incorrect case)
 CORS Error Response 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
Access-Control-Allow-Method: 
Put
...

Evaluating Access-Control-Request-Headers

The list of headers indicated by the client is also checked to ensure they are valid according to the configured policy. The web reverse proxy indicates to clients which headers are acceptable using the Access-Control-Request-Headers header.

If no headers are configured, the web reverse proxy allows any headers and returns the value provided by the client in the Access-Control-Request-Headers header.

If any allowed headers are configured, the headers are evaluated against the list of configured allowed headers (see allow-header) and list of simple headers (see Simple Methods and Headers) to determine if they are permitted. If all of the methods present in the request are permitted, the web reverse proxy returns to the client a list of all allowed headers in the Access-Control-Request-Headers header.
Note:
  • Header names are compared in a case sensitive manner.
  • Simple headers are only returned when the configured list of allowed methods for the policy is empty or if they are explicitly defined in the allow-header configuration entry.
Request Headers Response from policy containing:

allow-header = X-IBM-HEADER

allow-header = X-IBM-HEADER-2

 Response from policy containing:

allow-header =

 
OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: X-IBM-Header, X-IBM-HEADER-2, Accept
...
(Configured headers and simple headers, mixed cases)
 
204 NO CONTENT
Access-Control-Allow-Origin: https://test.ibm.com
Access-Control-Allow-Method: X-IBM-HEADER, X-IBM-HEADER-2
...
 
204 NO CONTENT
Access-Control-Allow-Origin: https://test.ibm.com
Access-Control-Allow-Method: X-IBM-HEADER, X-IBM-HEADER-2, Accept
...
 
OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: X-IBM-HEADER-3
...
(Headers which are not configured)
 CORS Error Response 
204 NO CONTENT
Access-Control-Allow-Origin: https://test.ibm.com
Access-Control-Allow-Method: X-IBM-HEADER-3
...
 
OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
Access-Control-Request-Method: PUT
...
(No headers)
 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
...
 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
...
 
OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: Accept, Accept-Language
...
(Just simple headers)
 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
...
 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
Access-Control-Allow-Headers: 
Accept, Accept-Language
...

Evaluating Access-Control-Max-Age

The web reverse proxy can indicate to the client how long (in seconds) they should cache the results of the pre-flight check using the Access-Control-Max-Age header.

If the maximum age entry (see max-age) is configured or invalid, no header is returned.

If a maximum age has been set, it returns to clients. Clients typically interpret the value in the following ways:
  • -1: The response should not be cached at all
  • 0: The client may cache this entry for any period of time it wishes
  • >0: The client should cache this entry for no longer than the number of seconds given.
Note: Many clients have a built-in maximum period of time that they cache pre-flight results for and this might be lower than the value returned by the web reverse proxy.
Request Headers Response from policy containing:allow-origin = https://test.ibm.com

max-age = 600

 Response from policy containing:allow-origin = https://test.ibm.com

max-age =

 
OPTIONS /resource HTTP/1.1
Origin: https://test.ibm.com
Access-Control-Request-
Method: GET
...
 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
Access-Control-Allow-Method: 
GET
Access-Control-Max-Age: 600
...
 
204 NO CONTENT
Access-Control-Allow-Origin: 
https://test.ibm.com
Access-Control-Allow-Method: 
GET
...