Enable RESTful Service CORS Support

Overview

This page describes how to enable Cross-Origin Resource Sharing (CORS) for Bloomreach Content RESTful services. Enabling CORS allows AJAX clients from other origins to access your REST endpoints.

When to Use

Enable CORS when you need to call Bloomreach Content RESTful services from web applications hosted on different domains. By default, browsers enforce the same-origin policy and block cross-domain AJAX requests. CORS support allows you to control which origins can access your APIs.

This guide applies to custom RESTful services configured using the REST Services Setup tool in Essentials.

Prerequisites

• Access to the Bloomreach Content Console
• Permissions to modify mount configuration or Spring configuration in your project
• For Option 2, ability to update the project's Maven dependencies and Spring configuration

Implementation Steps

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

Info: Available in brXM 12.3 and later.

Configure CORS by adding response headers directly to the mount configuration for your RESTful service.

1. In the Console, navigate to the hst:mount node for your RESTful service.
   For services created via the REST Services Setup tool, the node is typically at:
   /hst:hst/hst:hosts/dev-localhost/localhost/hst:root/api-manual
2. Add a multi-valued String property named hst:responseheaders.
3. Set the value to specify the allowed origin. For example:

   Access-Control-Allow-Origin: http://example.com/
   

   To allow all domains, use:

   Access-Control-Allow-Origin: *
   

4. The resulting YAML configuration resembles:

   /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]
   copy

5. Save your changes to the repository.

Verification

After updating the configuration, each response from the RESTful service includes the following header:

Access-Control-Allow-Origin: *

This configuration allows all domains to access the RESTful service. To restrict access, specify a particular domain in the header value. You can also add additional response headers for more granular control. Refer to MDN's CORS documentation for details.

Option 2: Configure CXF CORS Filter (for XM 12.2 and earlier)

If you are using brXM 12.2 or earlier, enable CORS by configuring the CXF CORS filter in your Spring configuration.

1. Add the CXF CORS dependency to your site module's pom.xml:

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

2. Edit the Spring configuration file:

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

3. Add the jaxrsRestCorsFilter bean:

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

4. Locate the essentialsRestEntityProviders bean and add a reference to jaxrsRestCorsFilter in the sourceList property:

     <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>
   copy

5. Save your changes and redeploy the site module.

Verification

After configuration, each RESTful service response to requests with an Origin HTTP header includes:

Access-Control-Allow-Origin: *

This allows all domains to access the RESTful service. For more restrictive policies, configure the jaxrsRestCorsFilter bean or use annotations on your REST resource classes. See the CXF CORS documentation for configuration examples.

Related Topics

• REST Services Setup tool
• Mount configuration
• MDN CORS documentation
• CXF CORS documentation