Cross Origin Resource Sharing Handler

Purpose

The Cross Origin Resource Sharing Handler lets you configure cross origin access to resources hosted by vWAF, as required.

Browsers regularly load resources such as images and style sheets from different origins (domain and port). However, by default, browsers prohibit scripts running in the browser to make cross origin requests. This is a security measure to help prevent attacks such as Cross Site Request Forgery. Therefore, you must configure cross origin resource sharing if it is necessary to allow JavaScript running in a browser in a different origin to access resources protected by vWAF.

Although most of the workload is handled by the browser, you must configure vWAF Cross Origin Resource Sharing appropriately. This allows vWAF to respond to Cross Origin Resource Sharing 'Preflight' OPTIONS requests; based on the handler attributes and rules, vWAF verifies whether or not to grant cross origin access to resources.

vWAF also detects if a request does not originate from a Cross Origin Resource Sharing compatible browser; if so, the request is denied.

The Cross Origin Resource Sharing Handler allows you to configure the relevant attributes and rules, as detailed below.

For more information regarding adding and editing Handlers, see Editing Handlers.

Severity

Events triggered by this handler are given the severity: Either INFO messages with no severity, or LOW severity. (For details on severity levels, see Severity of Events Triggered by Handlers).

Recommendations for use

You configure the required Cross Origin Resource Sharing Handler attributes and rules, as required for the application. You must Commit and activate the ruleset (see Committing and Activating Ruleset Changes).

Ensure you check and test your application to confirm the Cross Origin Resource Sharing Handler attributes satisfy the client side resource sharing requirements.

Attributes

Attribute Meaning

origins

To allow the browser access to resources forbidden by the same origin policy, specify the required locations:

  • "*" is the default. This allows requests from any origin.

    Note that for requests that require authentication, the handler attribute 'allow_authenticated' must be set to 'true', otherwise the request will fail. See below for more information regarding 'allow_authenticated'

  • To restrict cross site access from specified resources, replace "*" with the required locations. Each location is specified as protocol, hostname and port - for example, https://foo.com:443

    If you add a host name only, two entries http and https are added automatically. For example, if you enter 'foo', http://foo and https://foo are added automatically.

This attribute sets the corresponding CORS header: 'Access-Control-Allow-Origin'

allow_methods

Specify the allowed methods for CORS requests:

  • GET is the default value
  • Add additional methods, as appropriate.

    You must enable the same methods in the ValidHTTPMethod handler. The default values for the ValidHTTPMethod include GET, HEAD and OPTIONS.

This attribute sets the corresponding CORS header: 'Access-Control-Allow-Methods'.

The browser sends an 'Access-Control-Request-Method' header, as part of the preflight request, to verify the method for the CORS request. The "Access-Control-Allow-Methods" header confirms the allowed methods.

allow_authenticated

Specify whether or not authenticated CORS requests are allowed. This determines whether the browser is allowd to send authenticated requests (for example, a request that contains an 'Authorization' header or a 'Cookie' header).

The default is 'false'.

This attribute sets the corresponding CORS header: 'Access-Control-Allow-Credentials'

allow_header

Specify the non-standard HTTP headers allowed for CORS requests:

No headers are added by default.

The allowed headers include:

  • 'Accept'
  • 'Accept-Encoding'
  • 'Accept-Language'
  • 'Cache-Control'
  • 'Connection'
  • 'Content-Length'
  • 'Content-Type' - if the value is one of the following:
    • application/x-www-form-urlencoded
    • multipart/form-data
    • text/plain
  • 'DNT'
  • 'Host'
  • 'If-Modified-Since'
  • 'Keep-Alive'
  • 'Referer'
  • 'User-Agent'
  • 'X-CustomHeader'
  • 'X-Requested-With'
  • + all the CORS "allow headers"

This attribute sets the corresponding CORS header: 'Access-Control-Allow-Headers'. In a preflight request, the browser sends 'Access-Control-Request-Headers' to signal which headers will be sent. vWAF confirms the allowed headers using 'Access-Control-Allow-Headers'.

expose_header

Specify the non-standard HTTP response headers that the browser can expose for CORS requests. This is relevant where browsers use CORS in an API container, such as XMLHttpRequest or Fetch.

By default, only these simple response headers are exposed:

  • Cache-Control
  • Content-Language
  • Content-Type
  • Expires
  • Last-Modified
  • Pragma

If necessary, you must add the required response headers.

No headers are added by default

You must add all headers that are explicitly set in your API ('standard headers' may not be consistent across browsers, so ensure you add all required response headers)

This attribute sets the corresponding CORS header: 'Access-Control-Expose-Headers'

max_age

Specify how many seconds a browser can cache the result of a CORS 'Preflight' request (an OPTIONS request with special attributes). The default is 60 seconds.

This attribute sets the corresponding CORS header: 'Access-Control-Max-Age'

error_code

Defines the HTTP error code that vWAF returns when a request is denied. The default error code is 403.

For a list of the valid error codes, see HTTP Error Codes.

usertext

Optional:

You can specify text to be appended to log file entries created by this handler. For example, you could provide a brief description explaining how this handler is utilized in your deployment.

enable_logging

Disable this option if you do not require vWAF to create a log file entry each time the handler is executed. This may be appropriate, in detection mode, if you are concerned about the number and size of log files or you do not need to log entries by this handler.

When in detection mode, disabling logging makes the handler ineffective. Disabling logging also prevents the actions of the handler from being considered as candidates for the Top-10 lists in Attack Analysis, and from being listed in Reports. To decrease the size of the log files, you can enable reduced logging, which excludes all non-handler-related information from the log files (see Editing Applications).

For details regarding entries added to the log file by this handler, see the relevant section in Entries in Application-Specific Log Files.