IBM Integration Bus V10 includes new capability that allows administrators to enable Cross-Origin Resource Sharing, or CORS. By enabling CORS support in IBM Integration Bus, web pages can make requests to services, such as REST APIs or integration services, that are hosted on IBM Integration Bus.

Background

A web page can make requests to access other content, where that content is either hosted on the same domain or another domain. A web page can request static content, such as an image, JavaScript, or CSS file. Additionally, a web page can make a request for dynamic content, such as making a request to a REST API.

When these requests are made, the origin of the web page and the origin of the content that is being requested are compared. The origin is a combination of the scheme, host name, and port number. For example, the origin of https://mydomain.com:7843/path/to/index.html is https://mydomain.com:7843.

When the origins of the web page and the content that is being requested match, the request is always permitted. When the origins match, it is called a same-origin policy. However, when the origins do not match, a cross-origin request must be made.

When a cross-origin request is made, the server that is hosting the content that is being requested must permit the web browser that is displaying the web page to make the request. If the server does not permit the web browser to make the request, the request is rejected. The CORS specification describes the mechanism that allows the server to permit the web browser access to content that the server is hosting.

If the web browser rejects a request, then it will report the problem in the error console. If the request is being made by JavaScript code, then the HTTP request may be returned with a status code of 0.

Enabling CORS support

In IBM Integration Bus V10, CORS support is now available, but it remains disabled by default until you turn it on. The initial release of V10 only supported the HTTP listener for the integration server, however the recently released fix pack 1 for V10 extends this support to cover the HTTP listener for the integration node as well.

The out of the box default settings for CORS support have been chosen to make getting started as easy as possible. The default settings permit all origins to access deployed HTTP services, permit all HTTP methods, and also permit a common set of HTTP headers to be used in both requests and responses.

To enable CORS support, you just need to change one setting:

HTTP listener for the integration server

$ mqsichangeproperties IB10NODE -e default -o HTTPConnector -n corsEnabled -v true
BIP8071I: Successful command completion.

HTTP listener for the integration node (fix pack 1 or later)

$ mqsichangeproperties IB10NODE -b httplistener -o HTTPConnector -n corsEnabled -v true
BIP8071I: Successful command completion.

Note that there are a separate set of CORS settings for both HTTP and HTTPS. For HTTP, you must specify HTTPConnector as above. For HTTPS, substitute HTTPConnector with HTTPSConnector.

When you modify the CORS settings, those new settings take place immediately. There is no need to restart the integration server or integration node when you modify the CORS settings. However, any inflight requests currently being handled are unaffected by the changes.

Advanced CORS configuration

Whilst the out of the box default settings for CORS may be sufficient for some cases, they may not be sufficient for all. There are multiple options available for fine tuning the CORS configuration in IBM Integration Bus, and I will cover them here.

Any example commands below will cover the CORS settings for the HTTP listener for the integration server. To use the commands with the HTTP listener for the integration node, substitute -e default with -b httplistener. To use the commands for HTTPS settings instead of HTTP, substitute HTTPConnector with HTTPSConnector.

Restricting the list of permitted origins

The default value of the corsAllowOrigins setting is ‘*’, which means permit all origins. You may want to modify the CORS configuration so that only specific origins are permitted to make cross-origin requests to the services being hosted in IBM Integration Bus.

To restrict the list of permitted origins, modify the value of the corsAllowOrigins setting so that it contains a comma-separated list of permitted origins:

$ mqsichangeproperties IB10NODE -e default -o HTTPConnector -n corsAllowOrigins -v \"http://host1.ibm.com,https://host2.ibm.com:7843,http://host3.ibm.com:12345\"
BIP8071I: Successful command completion.

Restricting the list of permitted HTTP methods

The default value of the corsAllowMethods setting is ‘GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS’, which permits a web page to send HTTP requests using any of the listed HTTP methods. You may want to modify the CORS configuration so that only specific HTTP methods are permitted. For example, you may wish to restrict the list to HTTP methods that are only intended for information retrieval, not update or delete.

To restrict the list of permitted HTTP methods, modify the value of the corsAllowMethods setting so that it contains a comma-separated list of permitted HTTP methods:

$ mqsichangeproperties IB10NODE -e default -o HTTPConnector -n corsAllowMethods -v \"GET,HEAD,OPTIONS\"
BIP8071I: Successful command completion.

Permitting credential information to be sent in requests

The default value of the corsAllowCredentials setting is ‘false’, which means that web browsers will not pass any credential information in requests to services being hosted in IBM Integration Bus. Credential information includes HTTP Basic Authentication information, or HTTP cookies.

To permit credential information to be passed in requests, set the value of the corsAllowCredentials setting to ‘true’:

$ mqsichangeproperties IB10NODE -e default -o HTTPConnector -n corsAllowCredentials -v true
BIP8071I: Successful command completion.

Permitting additional HTTP headers to be sent in requests

The default value of the corsAllowHeaders setting is ‘Accept,Accept-Language,Content-Language,Content-Type’. A web browser will not permit an HTTP header to be sent in requests to services being hosted in IBM Integration Bus unless that header is a member of this list.

To allow a web browser to send additional HTTP headers in requests, modify the value of the corsAllowHeaders setting so that it contains a comma-separated list of permitted HTTP headers:

$ mqsichangeproperties IB10NODE -e default -o HTTPConnector -n corsAllowHeaders -v \"X-Header1,X-Header2,X-Header3\"
BIP8071I: Successful command completion.

Permitting HTTP headers sent in responses to be exposed to web pages

The default value of the corsExposeHeaders setting is ‘Content-Type’. A service being hosted in IBM Integration Bus will be able to return any HTTP header in a response to a request from a web browser, but the web browser will only expose those headers to the requesting code if that header is a member of this list.

To expose an HTTP header sent in a response to a web page, modify the value of the corsExposeHeaders setting so that it contains a comma-separated list of permitted HTTP headers:

$ mqsichangeproperties IB10NODE -e default -o HTTPConnector -n corsExposeHeaders -v \"X-ResponseHeader1,X-ResponseHeader2\"
BIP8071I: Successful command completion.

Enabling or disabling web browser caching of CORS settings

Depending on the request being made by the web browser, the web browser may issue a preflight cross-origin request. This preflight request is made to verify that the actual request is permitted before the web browser issues the actual request. Web browsers can cache the response to a preflight cross-origin request in order to reduce the number of requests made to a server. The default value of the corsMaxAge setting is ‘-1’, which means no specific value will be sent in the response to a preflight cross-origin. It is then up to the browser to determine whether or not to cache the request.

This caching can be explicitly disabled by setting the value of the corsMaxAge setting to ‘0’:

$ mqsichangeproperties IB10NODE -e default -o HTTPConnector -n corsMaxAge -v 0
BIP8071I: Successful command completion.

Alternatively, you can explicitly enable caching by specifying the time to cache the request in seconds as the value of the corsMaxAge setting:

$ mqsichangeproperties IB10NODE -e default -o HTTPConnector -n corsMaxAge -v 3600
BIP8071I: Successful command completion.

Resources

The CORS specification is available online:
http://www.w3.org/TR/cors/

Full information regarding IBM Integration Bus and CORS can be found in the product documentation:
http://www-01.ibm.com/support/knowledgecenter/#!/SSMKHH_10.0.0/com.ibm.etools.mft.doc/ap04190_.htm