PingGateway 2024.11

CorsFilter

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

Usage

{
  "name": string,
  "type": "CorsFilter",
  "config": {
    "policies": [ {
      "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
    }, …​ ],
    "failureHandler": Handler reference
  }
}

Properties

policies

"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, PingGateway tries them in the order they are declared. PingGateway selects the first matching policy.

"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 isn’t in the list of accepted origins, PingGateway invokes the failure handler or returns an HTTP 403 Forbidden response and stops processing the request.

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

Examples:

{
  "acceptedOrigins": [
    "https://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 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 isn’t allowed, the Access-Control-Allow-Methods header is omitted. The failure handler isn’t 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 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 isn’t allowed, the Access-Control-Allow-Headers header is omitted. The failure handler isn’t 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: Reject all requested headers.

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

A comma-separated list of case-insensitive response header names returned in the Access-Control-Expose-Headers header.

Only headers in this list, safe headers, and these 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 allowCredentials instead. Learn more in 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, https://www.example.com. If a port number isn’t defined, origins with no port number or with the default port number (80 for HTTP, 443 for HTTPS) are accepted.

failureHandler

"failureHandler": Handler reference, optional

Handler invoked during the preflight request when the request origin doesn’t match any of the acceptedOrigins defined in policies.

The failure handler isn’t invoked when requested headers or requested methods aren’t allowed.

Provide an inline Handler configuration object or the name of a handler object declared in the heap.

Default: PingGateway returns HTTP 403 Forbidden and stops processing the request.

More information

org.forgerock.http.filter.cors.CorsFilter

org.forgerock.openig.filter.CorsFilter

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