Enable RESTful Service CORS Support

Introduction

Goal

EnableCORS 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 theREST 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'smount configuration.

Using the Console, browse to thehst:mount node for your RESTful service(s). For custom RESTful services that were initially configured through theREST 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 valueAccess-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'ssite 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'ssite module:

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

Add ajaxrsRestCorsFilter bean as in the example below:

  <bean />

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

  <bean>    <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 anOrigin 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 thejaxrsRestCorsFilter Spring bean, or by adding annotations to your REST resource classes. See theCXF CORS documentation for examples.