Configure a local OS registry for the IBM MQ Console and REST API

We can configure a local operating system registry within the mqwebuser.xml file. The user names and passwords on the local operating system are used to authenticate and authorize users of the IBM MQ Console and the REST API.


Before starting

  • For client certificate authentication with the local OS authentication feature, the user identity is the common name (CN) from the distinguished name (DN) of the client certificate. If the user identity does not exist as an operating system user, client certificate login will fail and fallback to password based authentication.
  • To complete this task, we must be a privileged user.


With a local operating system registry, users and groups are automatically assigned a role:

  • Any user that is part of the 'mqm' group, or the 'QMQMADM' group on IBM i, is granted the MQWebAdmin and MFTWebAdmin roles.
  • All other users are granted the MQWebUser role.

For more information about these roles, see Roles on the IBM MQ Console and REST API.

A local operating system registry can only be used on UNIX, Linux, and Windows. Equivalent function is provided on z/OS by configuring a SAF registry. For more information, see Configure a SAF registry for the IBM MQ Console and REST API.


Procedure

  1. Copy the sample XML file local_os_registry.xml from the following path: MQ_INSTALLATION_PATH/web/mq/samp/configuration
  2. Place the sample file in the following directory: MQ_DATA_PATH/web/installations/installationName/servers/mqweb
  3. Optional: If we changed any configuration settings in mqwebuser.xml, copy them into the sample file.
  4. Delete the existing mqwebuser.xml file and rename the sample file to mqwebuser.xml.


What to do next

Choose how users authenticate:

    IBM MQ Console authentication options

    • Let users authenticate by using token authentication. In this case, a user enters a user ID and password at the IBM MQ Console log in screen. An LTPA token is generated that enables the user to remain logged in and authorized for a set amount of time. No further configuration is required to use this authentication option, but we can optionally configure the expiry interval for the LTPA token. For more information, see Configure the LTPA token expiry interval.
    • Let users authenticate by using client certificates. In this case, the user does not use a user ID or password to log in to the IBM MQ Console, but uses the client certificate instead. For more information, see Use client certificate authentication with the REST API and IBM MQ Console.

    REST API authentication options

    • Let users authenticate by using HTTP basic authentication. In this case, a user name and password is encoded, but not encrypted, and sent with each REST API request to authenticate and authorize the user for that request. In order for this authentication to be secure, we must use a secure connection. That is, we must use HTTPS. For more information, see Use HTTP basic authentication with the REST API.
    • Let users authenticate by using token authentication. In this case, a user provides a user ID and password to the REST API login resource with the HTTP POST method. An LTPA token is generated that enables the user to remain logged in and authorized for a set amount of time. For more information, see Use token-based authentication with the REST API. We can configure the expiry interval for the LTPA token. For more information, see Configure the LTPA token.
    • Let users authenticate by using client certificates. In this case, the user does not use a user ID or password to log in to the REST API, but uses the client certificate instead. For more information, see Use client certificate authentication with the REST API and IBM MQ Console.

Parent topic: Configure users and roles