CORS Directives

Cross-origin resource sharing or CORS is a feature of all modern browsers that allows certain otherwise disallowed requests to be made to a domain other than that on which the requesting page is hosted. Most notably Ajax/XHR style requests. By default browsers disallow these type of requests if the origin of the requesting page and the server do not match. CORS provides a mechanism for the server and browser to communicate to determine whether or not such requests should instead be allowed.

This is a very common requirement for RealityServer users since frequently the application page which is making requests to RealityServer is not hosted on RealityServer itself (although of course it can be). In this configuration RealityServer is effectively functioning as an API server and so needs to be set up to allow cross-origin requests using the CORS configuration directives.

CORS requests are identified when the HTTP header contains the Origin field, which contains the origin (eg: http://www.example.com) of the web page making the request. The CORS feature when configured allows RealityServer to respond to these requests by sending back the HTTP header Access-Control-Allow-Origin if the origin appears in the configuration.

The default realityserver.conf configuration which ships with RealityServer includes a commented out CORS configuration section. For most users uncommenting this and adding either a wildcard origin or the origin representing their specific server is sufficient to enable CORS. Here is an example configuration:

<user allowed_origins>
    origin www.example.com
    ## preflight support, allows all preflight requests
    methods GET,POST
    headers *
    max_age 3600
    allow_credentials true
</user>

The following sections provide the supported configuration directives for the CORS feature. These directives are to be defined inside the <user allowed_origins> context.

origin

Each origin must match the origin string that would be given by the browser. For example origin http://localhost:8080. There are shortcuts however for allowing both http:// and https:// origins simply by not defining a protocol. For example origin localhost:8080. Also the origin * wildcard is supported which will allow all origins. Multiple origins can be defined, duplicates will have no affect.

Additional wildcard functionality is available for matching multiple origins with complex naming without the need to specify each individually.

Here are some examples of valid origin directives:

# Allow any subdomain part of myhost.com:8080
origin http://*.myhost.com:8080

# Allow all subdomains servers1-6
origin http://servers[123456].myhost.com:8080

# Allow subdomain servers ending in any character
origin http://servers?.myhost.com:8080

# Allow any sub-subdomains part of server-a, server-b, server-c 
origin http://*.server-[abc].myhost.com:8080

# Allow a subdomain patter of ad.myhost.com at.myhost.com and ap.myhost.com
origin http://a[dtp].myhost.com:8080

# Allow single domain, but on any ports 8080 to 8089
origin http://web.server.com:808?

methods

If any of the following requirements are met, then a browser will perform a CORS preflight request:

• The HTTP method is not a GET, HEAD or POST.
• The Content-Type is not set to one of application/x-www-form-urlencoded, multipart/form-data or text/plain.
• A custom headers has been set.

If none of the above is performed then the preflight is skipped and the CORS request is made directly.

To enable support for preflight at least the methods directive must be supplied. headers is also usually supplied (see below) since preflight requests are most oftem triggered by custom headers on an XHR call.

A comma separated list of HTTP methods that are allowed. For example PUT, OPTIONS, DELETE GET. POST and HEAD can be set but they will not restrict the request. Also supports the * wildcard, which will return the same methods that were requested. The * must be the only value for this to work. If no methods are specified then it is assumed that no methods apart from the default ones are allowed (GET, POST and HEAD). Note that RealityServer only supports GET and POST requests.

Here are some examples of valid methods directives:

# Only allow these HTTP methods (in addition to GET, HEAD and POST).
methods PUT, DELETE

# Allow all methods
methods *

headers

A comma separated list of custom HTTP headers that are allowed. For example X-Custom-Header, X-Another-Header. Also supports the * wildcard, which will return the same headers that were requested. The * must be the only value for this to work. If no headers are specified then it is assumed that no custom headers are allowed.

Here are some examples of valid headers directives:

# Only allow these custom headers.
headers X-Custom-Header, X-Other-Custom-Header

# Allow all headers.
headers *

max_age

The value in seconds for how long the browser should cache the result from the preflight. This means that any changes made to the CORS config will not be picked up by the users if their results have been cached for too long. However each preflight request is an additional HTTP request so a balance must be found between these two requirements. If no max_age is specified, or is set to zero, or is not a number, then no caching will be performed and all CORS requests that require a preflight will perform a preflight.

Here are some examples of valid max_age directives:

# Cache for 60 seconds.
max_age 60

allow_credentials

When given the value true this will allow session cookies to be used for credentials. This also slightly changes how the normal CORS request is performed, for example the * wildcard will not be returned for the Allow-Origin header.

Here are some examples of valid allow_credentials directives:

# Allows credentials
allow_credentials true

Limitations

While the CORS feature does support preflight, it does not support preflight headers beyond the required ones, max-age. The required headers are Access-Control-Request-Method and Access-Control-Request-Headers.