Configuring CORS for the REST API

By default, a web browser does not allow scripts, such as JavaScript, to invoke the REST API when the script is not from the same origin as the REST API. That is, cross-origin requests are not enabled. You can configure Cross Origin Resource Sharing (CORS) to allow cross-origin requests from specified origins.

About this task

You can access the REST API through a web browser, for example through a script. As these requests are from a different origin to the REST API, the web browser refuses the request because it is a cross-origin request. The origin is different if the domain, port, or scheme is not the same.

For example, if you have a script that is hosted at http://localhost:1999/ you make a cross-origin request if you issue an HTTP GET on a website that is hosted at https://localhost:9443/. This request is a cross-origin request because the port numbers and scheme (HTTP) are different.

You can enable cross-origin requests by configuring CORS and specifying the origins that are allowed to access the REST API.

Procedure

Use one of the following methods to configure the host name:

From IBM® MQ 9.0.4, use the setmqweb properties command:
- View the current configuration by entering the following command and viewing the mqRestCorsAllowedOrigins and mqRestCorsMaxAgeInSeconds entries:
  dspmqweb properties -a
- Specify the origins that are allowed to access the REST API by entering the following command:
  setmqweb properties -k mqRestCorsAllowedOrigins -v allowedOrigins
  
  where allowedOrigins specifies the origin that you want to allow cross-origin requests from. You can use an asterisk surrounded by double quotation marks, "*", to allow all cross-origin requests. You can enter more than one origin in a comma-separated list, surrounded by double quotation marks. To allow no cross-origin requests, enter empty quotation marks as the value for allowedOrigins.
- Specify the time, in seconds, that you want to allow a web browser to cache the results of any CORS pre-flight checks by entering the following command:
  setmqweb properties -k mqRestCorsMaxAgeInSeconds -v time
For IBM MQ 9.0.3 and earlier, edit the mqwebuser.xml file:
1. Ensure that you are a privileged user.
2. Open the mqwebuser.xml file.
  The mqwebuser.xml file can be found in one of the following directories:
  - On UNIX, Linux®, and Windows: MQ_DATA_DIRECTORY/web/installations/installationName/servers/mqweb
  - On z/OS®: WLP_user_directory/servers/mqweb
    where WLP_user_directory is the directory that was specified when the crtmqweb.sh script ran to create the mqweb server definition.
3. Configure CORS by adding or uncommenting the following lines in the mqwebuser.xml file:
```
<variable name="mqRestCorsAllowedOrigins" value="https://localhost:9883"/>
<variable name="mqRestCorsMaxAgeInSeconds" value="120"/>
```
4. Change the value of the mqRestCorsAllowedOrigins variable to the origin that you want to allow cross-origin requests from. You can use an asterisk, *, to allow all cross-origin requests, or you can enter more than one origin in a comma-separated list.
5. Change the value of the mqRestCorsMaxAgeInSeconds variable to the time, in seconds, that you want to allow a web browser to cache the results of any CORS pre-flight checks.

Example

The following example shows cross-origin requests enabled for http://localhost:9883, https://localhost:1999, and https://localhost:9663. The maximum age of cached results of any CORS pre-flight checks is set to 90 seconds:

setmqweb -k mqRestCorsAllowedOrigins -v "http://localhost:9883,https://localhost:1999,https://localhost:9663"
setmqweb -k mqRestCorsMaxAgeInSeconds -v 90