Configuring CORS

CORS can be configured to allow web-browser based clients on other domains to access the CollectionSpace REST API.

Creating a file to store local configuration

Your configuration file should be placed in the $CSPACE_JEESERVER_HOME/cspace/config/services/local directory on the CollectionSpace server.

  1. Create the local directory if it does not exist.

  2. Inside that directory, create a file with any name of your choosing, ending with.xml; for example, services-config-cors.xml. This local configuration file will be merged with theservices-config.xml and services-config-security.xml files, found in $CSPACE_JEESERVER_HOME/cspace/config/services. You may add more than one .xml file to the local directory if you want to split your configuration into multiple files. If more than one .xml file is present in local, the files are merged into the configuration in alphabetical order.

  3. Add configuration to your file(s), following the example and instructions below.

Your local configuration is merged with the default configuration files when CollectionSpace starts. For debugging, the output of the merge is written to $CSPACE_JEESERVER_HOME/cspace/config/services/service-config.merged.xml

CORS configuration settings

Your merged XML file must conform to the XML schema at https://github.com/collectionspace/services/blob/v8.0-branch/services/config/src/main/resources/service-config.xsd . That schema defines the security/cors element that contains the configuration for CORS.

The following example shows a typical CORS configuration file:

<?xml version="1.0" encoding="UTF-8"?> <svc:service-config xmlns:svc='http://collectionspace.org/services/config' xmlns:merge='http://xmlmerge.el4j.elca.ch' > <security> <cors> <allowed-origin>https://cspace.example.org</allowed-origin> <allowed-origin>https://another.example.org</allowed-origin> <max-age>P1D</max-age> </cors> </security> </svc:service-config>

The merge result can be fine tuned by adding attributes from the merge namespace defined in the example. In most cases, the default merge behavior (no merge attributes, as above) is sufficient. See the XmlMerge documentation for details.

Some important elements inside cors include:

allowed-origin

An origin for which cross-origin requests are allowed. Multiple allowed-origin elements can be used to specify multiple origins.

max-age

How long, as a duration, the response from a pre-flight request can be cached by clients. Specified in ISO-8601 duration format: PnDTnHnMn.nS

Â