Enable RESTful Service CORS Support

Introduction

Goal

Enable CORS support to allow access to Bloomreach Experience Manager RESTful services via AJAX.

Use Case

Calling a Bloomreach Experience Manager RESTful service via AJAX confronts you with the same-origin policy. By default, browsers do not allow cross-domain Ajax requests. Bloomreach Experience Manager supports Cross-Origin Resource Sharing (CORS) to allow such cross-domain requests.

This page describes how to enable CORS for custom RESTful services that were initially configured through the REST Services Setup tool in Essentials.

Enable CORS

Option 1 (Recommended): Configure Response Headers on Mount Node

The easiest way to enable CORS for a Bloomreach Experience Manager RESTful service is by specifying the Access-Control-Allow-Origin response header in the service's mount configuration.

Using the Console, browse to the hst:mount node for your RESTful service(s). For custom RESTful services that were initially configured through the REST Services Setup tool in Essentials, that is the node at /hst:hst/hst:hosts/dev-localhost/localhost/hst:root/api-manual.

Add a multi-valued String property hst:responseheaders and add the value Access-Control-Allow-Origin: http://example.com/.

A YAML representation of the node would then look similar to this:

/hst:hst/hst:hosts/dev-localhost/localhost/hst:root/api-manual:
  jcr:primaryType: hst:mount
  jcr:uuid: a5f7da64-2106-4c3e-bcdf-cb249c9fe01a
  hst:alias: api-manual
  hst:ismapped: false
  hst:namedpipeline: JaxrsRestPlainPipeline
  hst:responseheaders: ['Access-Control-Allow-Origin: */']
  hst:types: [rest]

After writing your changes to the repository, each call to the RESTful service will now automatically include the following header in the response:

Access-Control-Allow-Origin: *

That will grant all domains access to the RESTful service. More fine-grained access control can be achieved by configuring a specific domain in the Access-Control-Allow-Origin header and/or configuring additional response headers (see e.g. MDN's CORS documentation for more information).

Option 2: Configure CXF CORS Filter

Alternatively, CORS can be enabled by configuring the CXF CORS filter through Spring. This is the only option available in Bloomreach Experience Manager 12.2 and earlier.

First, add the following CXF dependency to your project's site module:

site/pom.xml

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-rs-security-cors</artifactId>
  <version>${cxf.version}</version>
</dependency> 

Second, modify the following Spring configuration file in your project's site module:

site/components/src/main/resources/META-INF/hst-assembly/overrides/spring-plain-rest-api.xml

Add a jaxrsRestCorsFilter bean as in the example below:

  <bean id="jaxrsRestCorsFilter" class="org.apache.cxf.rs.security.cors.CrossOriginResourceSharingFilter" />

Find the essentialsRestEntityProviders bean and add a reference to jaxrsRestCorsFilter to the sourceList property as in the example below (line marked with comment "enable CORS"):

  <bean id="essentialsRestEntityProviders" class="org.springframework.beans.factory.config.ListFactoryBean">
    <property name="sourceList">
      <list>
        <ref bean="jaxrsRestCorsFilter"/> <!-- enable CORS -->
        <ref bean="jaxrsHippoContextProvider"/>
        <ref bean="jaxrsRestExceptionMapper"/>
      </list>
    </property>
  </bean>

Each call to the RESTful service that includes an Origin HTTP header will now automatically include the following header in the response:

Access-Control-Allow-Origin: *

That will grant all domains access to the RESTful service. More fine-grained access control can be achieved by configuring the jaxrsRestCorsFilter Spring bean, or by adding annotations to your REST resource classes. See the CXF CORS documentation for examples.