Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Process CORS Request Assertion

Last update June 29, 2017

The Process CORS Request assertion allows a service to handle Cross-Origin Resource Sharing (CORS). This assertion sets the appropriate headers in the response message for CORS requests and if the origin conditions are met. 

Note the following when using this assertion:

  • The service must have the OPTIONS method enabled.
  • There should be policy logic that returns HTTP status 200 immediately upon all successful CORS preflight requests. See the example below.
  • The Process CORS Request assertion appears before any authentication.

Example:

The following sample policy uses the Process CORS Request assertion:

The Return Template Response to Requestor Assertion in the policy returns an HTTP status 200:


Note: Do not select the "Send Response Immediately" option, otherwise the CORS request will not reach the endpoint.

Context Variables

The following context variables are set, regardless of whether the assertion succeeds or fails:

Name Description
<prefix>.isPreflight Returns "true" if the request is a preflight request, otherwise returns "false".
<prefix>.isCORS

Returns "true" if the request is a CORS request (contains the Origin header), otherwise returns "false".

Note: This variable always returns "true" if <prefix>.isPreflight is "true".

Cluster Properties

The following cluster-wide property is set to use multi valued assertions:

Name Description
cors.useMultiValuedHeaders

Controls whether the Process CORS Request assertion uses multi-valued headers.

Default: false

Properties

Setting What you should know...
Accepted Origins tab

Define the allowable origins of the CORS request. If entering specific origins, the "Accept Same-Origin Requests" option serves as a shortcut to manually entering the request's origin.

The assertion fails if a request comes from an unspecified origin.

Note: When you define allowable origins, the origin header in the request must be a 1:1 match with the accepted-origin header in the response, otherwise the assertion fails. For example, if the request header contains "http://example.com" but the response header contains "example.com", then a match does not occur.

Accepted Headers tab

Define the allowable headers in a CORS request.

The assertion fails if an unspecified header is encountered.

Exposed Headers tab Define the header names to insert into the Access-Control-Expose-Header header in the CORS response message.
Allowed Methods tab

Select which HTTP methods are allowed. These methods are compared against the Acces-Control-Requested-Method header in preflight requests. At least one method must be selected.

Tip: Select 'Other' to allow all non-standard HTTP methods through. Use policy logic for more precise control over non-standard methods.

Common Settings
Require CORS Select this option to fail the assertion if an Origin header is not present in the request message.
Supports Credentials

Select this option to indicate credentials are supported. It will:

  • Add an Access-Control-Allow-Credentials header to the response message
  • Set the above header to the value of the Origin header from the request

If this option is not selected, then the Access-Control-Allow-Credentials header is set to * (that is, wildcard).

Response Cache Age Select this option to add an Access-Control-Max-Age header to the response message. Specify the cache age in the adjacent box. You may specify a context variable.
Variable Prefix Specify a prefix to be added to the context variables created by this assertion. The default is cors.

Frequently Asked Questions

Question Answer
What is a "preflight" request? Under the CORS standard, a browser sends a "preflight" request to determine whether it has permission to perform the action. Only when the back end server approves will the browser send the actual request with the actual HTTP request method.
Do I need to specifically create a "preflight" request? No, the browser automatically sends a preflight request if it is required.
What credentials are used? Credentials may include Cookies and HTTP Authentication data.
Which browsers support CORS? CORS is supported by most modern web browsers.
Which audit codes are returned by this assertion? Warnings are returned using audit code -5. Informational messages are returned using audit code -3.
Why am I am getting duplicate headers in the response message? The Process CORS Request assertion adds headers in the response message for CORS requests, provided that the origin conditions are met. If you are seeing duplicate headers, that means your back-end API is also adding a header to the response. Try to set your back-end API to not add headers. You can use policy logic to remove the duplicate headers.
Was this helpful?

Please log in to post comments.

  1. Victor Kazakov
    2018-05-15 12:45

    For anyone having issues with IE, I just learned this from a Gateway user: We have been experiencing a CORS issue for the past week with just the IE browser. We came to learn that port 8443 is a restricted port in IE, which causes the issue. We changed the port to 5001 in our endpoint and it worked great.