Configure host header validation for the IBM MQ Console and REST API

We can configure the mqweb server to restrict access to the IBM MQ Console and REST API such that only requests that are sent with a host header that matches a specified allowlist are processed. An error is returned if a host header value that is not on the allowlist is used.


Note: Wherever possible, the term allowlist has replaced the term whitelist.

The mqweb server uses virtual hosts to define the allowlist of acceptable host headers. For more information about virtual hosts, see the WebSphere Liberty documentation: https://www.ibm.com/support/knowledgecenter/en/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/cwlp_virtual_hosts.html

To complete this task, we must be a user with sufficient privileges to edit the mqwebuser.xml file:

  • On z/OS, we must have write access to the mqwebuser.xml file.
  • On all other operating systems, we must be a privileged user.


Procedure

  1. Open the mqwebuser.xml file. This file is in one of the following locations:

    • On UNIX, Linux, and Windows: MQ_DATA_PATH/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 script ran to create the mqweb server definition.

  2. Add or uncomment the following code in the mqwebuser.xml file: 
    <virtualHost allowFromEndpointRef="defaultHttpEndpoint" id="default_host">
        <hostAlias>localhost:9080</hostAlias>
</virtualHost>
  3. Edit the <hostAlias> field, inserting the hostname and port combination that we want to allow. This combination might be the hostname and port name that we used in the configuration of the mqweb server. For example, if we use the default configuration of localhost:9443, you might want to use localhost:9443 in the <hostAlias> field.

    If necessary, we can add multiple <hostAlias> fields within the <virtualHost> tags to allow more hostname and port combinations. For example, to allow host headers that use an HTTP port as well as host headers that use the HTTPS port.

Parent topic: IBM MQ Console and REST API security