Cross-Origin Resource Sharing (CORS) is a security mechanism to protect against the use of unwanted cross origin requests. If a HTML page contains resources that reside on another domain, we consider this a cross origin request. Some web domains don’t allow cross reference requests. This document contains a description on how to use CORS with TIBCO BusinessWorks 6.

This howto assumes the following:

1. The use of BW6.5 (things may also work in newer versions of BW)
2. PostMan is installed.

Sample project:

cors.zip

Understanding CORS

In order to be able to implement CORS in BW6, it is important to understand CORS. It is beyond the scope of this document to provide an in-dept description of CORS. I would like to refer to this webpage for a detailed description.

To summarize CORS:

Same origin request

Any web page may contain references to other web resources. Being it pictures, stylesheets or API calls. As long as these resources are on the same domain as the original web page, the web browser will fetch the resources without doing any checking. 

Example:

Let’s assume you loaded a web page http://www.mydomain.com/index.html. This HTML file contains a picture (a resource) with the url: http://www.mydomain.com/picture.jpg.  In this case the browser will fetch the picture without doing any additional checks.

Cross origin request

If a resource nevertheless has a different domain name, protocol or port, it is considered a cross origin request. In this case the browser will do a CORS check to make sure the resource can be fetched.

Example: Let’s assume you loaded a web page http://www.mydomain.com/index.html. This HTML file contains a picture (a resource) with the url: http://www.anotherdomain.com/picture.jpg. A CORS enabled browser will in this case do a CORS check. The same will happen if the web page http://www.mydomain.com/index.html contains JavaScript code that invokes an API with the url: http://api.mydomain.com/resource.

The way in which a CORS check is carried out depends on the type of resource at stake. Two types are distinguished:

• Simple requests. If the request is a GET, a HEAD or a POST request AND only a number of predefined headers are used (see for more details here).  The request is simple. In this case the request to the web server is made. The web server will provide CORS information. Based on this information the web browser will determine if the request should have been made. If not, the browser will throw an error.
• Preflighted requests. For all other requests, the browser will first do an OPTIONS request. Based on the response from that OPTIONS request, the actual response to the intended resource is made.

Please take a look at this webpage for details and examples.

BusinessWorks 6

BusinessWorks contains a standard CORS implementation. 

Standard CORS BW6 implementation

In order to show the standard CORS settings for BW6 resource the attached project contains a resource named:POST /cors.  This resource contains a standard restful function that takes a string as input en returns the word ‘response’. See the swagger below:

 

Unfortunately the swagger interface doesn’t provide the option to inspect the HTTP headers that are returned by BW. In order to see these, a tool like Postman can be used. Please mind the URL Win-1uq8G1NVJPl.localdomain that I used is specific for my computer. Please lookup your local hostname or use use localhost. It is important to use the right port (the port configured in the HTTP resource in BW).

In order to inspect the HTTP headers are being returned, I used Postman to invoke the /cors resource.

The postman output reveals that BW6 provides three standard CORS related HTTP headers: 

• Access_Control_Allow-Origin, 
• Access-Control-Allow-Methods, 
• Access-Control-Allow-Headers.

 

As you can see by default the header ‘Access-Control-Allow-Origin’ is set to ‘*’ which means that the resource can be called from any domain.

Remark: Although the OPTIONS method is not enabled in the swagger interface it is automatically implemented by BW. You may want to try to invoke this method using postman to verify that it does exist. It does return standard CORS headers.

 

Using alternative CORS settings

Unfortunately it is not possible to modify CORS headers within the process that implements the resource. In order to overwrite the standard CORS headers it is necessarily to create a proxy in BW. This proxy is invoked (instead of calling the /cors resource directly). The sample application contains a sample proxy (proxy.bwp). This process contains three activities:

• HTTPReceiver. This activity listens for incoming HTTP requests. Please mind: this listener must not be configured on the same port as the /cors resource (see for details later in this document).
• SendHTTPRequest. This activity forwards the incoming request to the /cors resource. 
• SendHTTPResponse. This activity replies to the sender. 

In the SendHTTPRequest make sure to configure the necessary minimal mapping.

 

In the SendHTTPResponse, make sure you:

1. Map at least the ascii content to be returned.
2. Set the CORS related headers that you want to return.

The HTTP connector that you use for the proxy must be configured to use a different port than the connector used for you restful service.

The client resource used for the SendHTTPRequest activity must be configured to talk to the port that you configured for the HTTP resource from the restful service:

 

In order to test the proxy open PostMan and invoke the service on the proxy port. In my case: http://WIN-1UQ8G1NVJPI.localdomain:8088/cors. Again the hostname is specific for my machine. Lookup your own local hostname or use localhost.

IMPORTANT: Add the content-Type header with the value application/json to the request (see picture below).

As you can see the modified CORS headers are now returned.