PingGateway 2024.9

CorsFilter

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

Usage

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

Properties

"policies": array of objects, required

One or more 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.

{
  "acceptedOrigins": [ 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": [ configuration expression<url>, ... ] or "*" //deprecated
}
"acceptedOrigins": array of configuration expression<urls> or "*", required

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

If the request origin is not in the list of accepted origins, the failure handler is invoked or an HTTP 403 Forbidden is returned, and the request stops being executed.

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:

{
  "acceptedOrigins": [
    "http://www.example.com",
    "https://example.org:8433"
  ]
}
{
  "acceptedOrigins": "*"
}
"acceptedMethods": array of configuration expression<strings> 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.

In preflight requests, browsers use the Access-Control-Request-Method header to let the server know which HTTP method might be used in the actual request.

  • If all requested methods are allowed, the requested methods are returned in the preflight response, in the Access-Control-Allow-Methods header.

  • If any requested method is not allowed, the Access-Control-Allow-Methods header is omitted. The failure handler is not invoked, but the user agent interprets the preflight response as a CORS failure.

Examples:

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

Default: All methods are rejected.

"acceptedHeaders": array of configuration expression<strings> 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.

In preflight requests, browsers use the Access-Control-Request-Headers header to let the server know which HTTP headers might be used in the actual request.

  • If all requested headers are allowed, the requested headers are returned in the preflight response, in the Access-Control-Allow-Headers header.

  • If any requested header is not allowed, the Access-Control-Allow-Headers header is omitted. The failure handler is not invoked, but the user agent interprets the preflight response as a CORS failure.

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

A flag 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

"origins": list of configuration expression<url> or "*", required
This property is deprecated; use acceptedOrigins instead. For more information, refer to the Deprecated section of the Release Notes.

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.

"failureHandler": Handler reference, optional

Handler invoked during the preflight request, when the request origin does not match any of the acceptedOrigins defined in policies.

The failure handler is not invoked when requested headers or requested methods are not allowed.

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.

More information

org.forgerock.http.filter.cors.CorsFilter

org.forgerock.openig.filter.CorsFilter

https://fetch.spec.whatwg.org/#http-cors-protocol