Using OS userids for MQ Console and MQ REST authentication

On AIX, Linux and Windows from IBM MQ 9.0.4 and onwards you can use OS userids to authenticate your access to the MQ Console and MQ REST API.

I will discuss the changes in 9.0.4, and why you may wish to take advantage of these changes, but before I describe them, it is probably worth taking a moment to describe the authentication options available before the new feature was added.

Basic Registry: The userids and passwords are defined in the mqwebuser.xml file. Userids also may be assigned to groups of users. In addition, the userids or groups may be assigned to roles (more on that later).

LDAP Registry: LDAP Userids and groups are assigned to roles as above, however the userids are not defined in the xml file but instead on the LDAP server. The LDAP server to use is defined here, and also what subset of the LDAP userids can be used for MQ Console/REST authentication.

Particularly if you are using Basic registry, you may find the new local OS authentication a more attractive alternative.

(On z/OS, since IBM MQ version 9.0.2, Users of the MQ REST API and MQ Console have been able to achieve similar goals by making use of the System Authorization Facility — see footnote (4).)

Addition of OS userids for authentication

To authenticate using local OS userids, you will of course need to create the userids you wish to use on the system that is running your MQ Console and serving your REST calls. These can be created using your platform’s usual userid creation tools. To assign them to groups, you may use your platform’s regular userid administration commands.

In the mqwebuser.xml file, you may assign any of these local OS userids and local OS groups to each of the defined roles. These are defined independently for the MQ Console and MQ REST API and for each, the following options are offered (see footnote (3) for further information):

  • MQWebUser – “User” access to the MQ REST API and/or MQ Console. What exact options can be used is determined by the OAM (Object Authority Manager) permissions granted to that particular user.
  • MQWebAdmin – Full “Administrator” access to the MQ REST API and/or MQ Console. As above but the userid used when checking required access is the userid MQ Console is running under.
  • MQWebAdminRO – Authority to view anything an Administrator can view, but with no ability to change anything using the MQ REST API and/or MQ Console

What advantages does this bring?

Access to MQ objects

The default MQ OAM (Object Authority Manager) grants or denies access to MQ objects such as queues dependant on the OS userid used or the OS group the id belongs to. (See footnote (1))

This means that, even though an MQ Console using Basic Registry userids does not use OS userids for logon authentication, it will still need to check against them for access to MQ objects. Therefore you will need to define local OS userids and groups on the system that exactly match the basic registry ones so that appropriate permissions may be granted to them. The same applies to MQ REST API.

If you use local OS authentication, you need only define the userid and group once. With basic registry you must create the ids both in the Basic Registry and as local OS userids and groups and are required to keep the userids and group memberships in step yourself.

Essentially, for Basic Registry you might have:

Whereas for the same system using local OS authentication, you would have:

Protection of userids and passwords

When using Basic Registry, userids and passwords are defined in the mqwebuser.xml file in clear text. An additional step may be (and absolutely should be) run to encode or encrypt the passwords. This step must be re-run any time any password is changed or when any userid is added. With OS userids, this step is unneccessary as the passwords are held securely by the OS in the usual way.

OS userid/password/group support

When defining the userids that the MQ Console and MQ REST API use as local OS userids and not as flat text in the basic registry, you will automatically gain the benefit of the userid and password infrastructure provided by your OS. Dependant on OS, this might include such things as:

  • enforcement of local userid naming policies
  • password strength enforcement
  • password expiry
  • PAM (Pluggable Authentication Module) support – UNIX/Linux only (enabled on by setting the usePam property in the mqwebuser.xml to “true”))

Configuring the MQ REST API and MQ Console

Instructions for this can be found in the Knowledge Center (see footnote (2)). MQ ships a set of sample configuration files which you may copy in place of the default mqwebuser.xml file as a starting point. These samples now include a new file, called local_os_registry.xml which enables local OS authentication.

The full set of samples can be found here:
WINDOWS: C:\Program Files\IBM\MQ\web\mq\samp\configuration\
LINUX: /opt/mqm/web/mq/samp/configuration/
AIX: /usr/lpp/mqm/web/mq/samp/configuration/

and the mqwebuser.xml file that you should replace with your tailored one, can be found here:
WINDOWS: C:\ProgramData\IBM\MQ\web\installations\\servers\mqweb\
LINUX: /var/mqm/web/installation//servers/mqweb/
AIX: /var/mqm/web/installation//servers/mqweb/

The main (but not the only) change in the local OS authentication sample is the addition of an additional feature within the <featureManager> tag and this is:

With this feature installed, WebSphere Application Server Liberty userid authentication is handled by the MQ plugin. As a result, MQ calls out to OS system services to authenticate userids.


Local OS authentication offers a third way of configuring MQ REST API and MQ Console security in addition to the previously available Basic Registry and LDAP Registry. It delivers considerable advantage, especially over Basic Registry authentication.

  • There is less work to do. No duplicate user and group definitions to create.
  • Easier and less error prone to maintain. There are no userids and group definitions in the mqwebuser.xml file that you must manually keep in step with the actual userids and groups defined on the OS to ensure your authentication continues to work as expected.
  • Allows use of standard OS tools for userid and group creation and password management, and lets you take advantage of all the benefits of this tooling.
  • Passwords are secured by the OS and do not rely on user action to encrypt or secure.


(1) Using a custom authorization service:

(2) Configuring MQ Rest API and MQ Console security

(3) Roles on the MQ REST API and MQ Console

(4) Configuring System Authorization Facility interface

Leave a Reply