CorsFilter

Configures policies for cross-origin resource sharing (CORS), to allow cross-domain requests from user agents.

Usage

{
   "name": string,
   "type": "CorsFilter",
   "config": {
     "policies": [ configuration expression<object>, ... ],
     "failureHandler": Handler reference
   }
}

Properties

"policies": list of configuration expression<object>, required

A list of policies to apply to the request. A policy is selected when the origin of the request matches the accepted origins of the policy.

When multiple policies are declared, they are tried in the order that they are declared, and the first matching policy is selected.

When no policy matches during a preflight request, the failure handler is invoked or an HTTP 403 is returned. 

{
  "origins": [ configuration expression<url>, ... ] or "*",
  "acceptedMethods": [ configuration expression<string>, ... ] or "*",
  "acceptedHeaders": [ configuration expression<string>, ... ] or "*",
  "exposedHeaders": [ configuration expression<string>, ... ],
  "maxAge": configuration expression<duration>,
  "allowCredentials": configuration expression<boolean>
}
"origins": list of configuration expression<url> or "*", required

A comma-separated list of origins, to match the origin of the CORS request. Alternatively, use * to allow requests from any URL.

Origins are URLs with a scheme, hostname, and optionally a port number, for example, http://www.example.com. If a port number is not defined, origins with no port number or with the default port number (80 for HTTP, 443 for HTTPS) are accepted.

Examples:

{
  "origins": [
    "http://www.example.com",
    "https://example.org:8433"
  ]
}
{
  "origins": "*"
}
"acceptedMethods": list of configuration expression<string> or "*", optional

A comma-separated list of case-sensitive HTTP method names that are allowed when making CORS requests. Alternatively, use * to allow requests with any method.

The Access-Control-Request-Method header is used by browsers in preflight requests, to let the server know which HTTP method will be used in the actual request. If a method is allowed, it is returned in the preflight response, in the Access-Control-Allow-Methods header.

Examples:

{
  "acceptedMethods": [
    "GET",
    "POST",
    "PUT",
    "MyCustomMethod"
  ]
}
{
  "acceptedMethods": "*"
}

Default: All methods are rejected.

"acceptedHeaders": list of configuration expression<string> or "*", optional

A comma-separated list of case-insensitive request header names that are allowed when making CORS requests. Alternatively, use * to allow requests with any header.

The Access-Control-Request-Headers header is used by browsers in preflight requests, to let the server know which HTTP headers might be used in the actual request. If all requested headers are allowed, they are returned in the preflight response, in the Access-Control-Allow-Headers header. If any of the requested headers are not allowed, the Access-Control-Allow-Headers header is omitted.

Examples:

{
  "acceptedHeaders": [
    "iPlanetDirectoryPro",
    "X-OpenAM-Username",
    "X-OpenAM-Password",
    "Accept-API-Version",
    "Content-Type",
    "If-Match",
    "If-None-Match"
  ]
}
{
  "acceptedHeaders": "*"
}

Default: All requested headers are rejected.

"exposedHeaders": list of configuration expression<string>, optional

A comma-separated list of case-insensitive response header names that are returned in the Access-Control-Expose-Headers header. Only headers in this list, safe headers, and the following simple response headers are exposed to frontend JavaScript code:

  • Cache-Control

  • Content-Language

  • Expires

  • Last-Modified

  • Pragma

  • Content-Type

Example:

{
  "exposedHeaders": [
    "Access-Control-Allow-Origin",
    "Access-Control-Allow-Credentials",
    "Set-Cookie"
  ]
}

Default: No headers are exposed.

"maxAge": configuration expression<duration>, optional

The maximum duration for which a browser is allowed to cache a preflight response. The value is included in the Access-Control-Max-Age header of preflight responses.

When this maxAge is greater than the browser's maximum internal value, the browser value takes precedence.

Default: 5 seconds

"allowCredentials": configuration expression<boolean>, optional

Whether to allow requests that use credentials, such as cookies, authorization headers, or TLS client certificates.

Set to true to set the Access-Control-Allow-Credentials header to true, and allow browsers to expose the response to frontend JavaScript code.

Default: False

"failureHandler": handler reference, optional

Handler to treat the request when no policy matches during a preflight request.

Provide an inline handler configuration object, or the name of a handler object declared in the heap. See also Handlers.

Default: HTTP 403 Forbidden, the request stops being executed.

Read a different version of :