Configure users and roles

To make use of the IBM MQ Console or the REST API, users need to authenticate against a user registry, defined to the mqweb server.

Authenticated users need to be a member of one of the groups that authorizes access to the capabilities of the IBM MQ Console and REST API. By default, the user registry does not contain any users; these need to be added by editing the mqwebuser.xml file.

When you configure users and groups, you first configure a user registry to authenticate users and groups against. This user registry is shared between the IBM MQ Console and the REST API. We can control whether users and groups have access to the IBM MQ Console, REST API, or both, when you configure roles for your users and groups.

After you configure the user registry, you configure roles for the users and groups to grant them authorization. There are three roles available, and each role grants a different level of access. For more information, see Roles on the IBM MQ Console and REST API.

A number of sample XML files are provided with the mqweb server to make the configuration of users and groups simpler. This task describes how to use the samples and adjust them for your environment.

Users who are familiar with configuring security in WebSphere Application Server Liberty (WLP) might prefer not to use the samples. WLP provides other authorization capabilities in addition to the ones documented here.

For information about MFT roles, and an example, see Configure MFT REST API security

Procedure

Ensure that you are a privileged user.
Copy one of the sample XML files from one of the following paths:
- On UNIX, Linux , and Windows: MQ_INSTALLATION_PATH /web/mq/samp/configuration
- On z/OS®: PathPrefix /web/mq/samp/configuration
  where PathPrefix is the IBM MQ Unix System Services Components installation path.
Place the sample file in the appropriate directory:
- 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.
Optional: If you changed any configuration settings in mqwebuser.xml, copy them into the sample file.
Delete the existing mqwebuser.xml file and rename the sample file to mqwebuser.xml.
Edit the new mqwebuser.xml file to add users and groups as necessary:
- For security setups based off the basic_registry.xml sample, add users and groups within the basicRegistry tags.
  
  Be aware that any user with the MQWebUser role can perform only the operations that the user ID is granted to perform on the queue manager. Therefore, the user ID defined in the registry must have an identical user ID on the system on which IBM MQ is installed. These user IDs must be in the same case, or the mapping between the user IDs can fail.
  
  For more information about configuring basic user registries, see Configure a basic user registry for Liberty in the WebSphere Application Server Liberty documentation.
- For security setups based off the local_os_registry.xml sample, the registry accesses the local operating system to validate passwords, identify users and calculate group membership. This type of user registry is enabled by adding <feature>localOSAuthenticationMQ-1.0</feature> to the featureManager section of the mqwebuser.xml file.
  
  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.
- For security setups based off the ldap_registry.xml sample, change the LDAP registry settings within the ldapRegistry and idsLdapFilterProperties tags.
  
  Be aware that any user with the MQWebUser role can perform only the operations that the user ID is granted to perform on the queue manager. Therefore, the user ID defined on the LDAP server, must have an identical user ID on the system on which IBM MQ is installed. These user IDs must be in the same case, or the mapping between the user IDs can fail.
  
  For more information about configuring LDAP registries, see Configure LDAP user registries in Liberty in the WebSphere Application Server Liberty documentation.
Edit the new mqwebuser.xml file to assign roles to users and groups.
There are three roles available that authorize users and groups to use the IBM MQ Console, and the REST API. Each role grants a different level of access. For more information, see Roles on the IBM MQ Console and REST API.
- To assign roles and grant access to the IBM MQ Console, add your users and groups between the appropriate security-role tags within the <enterpriseApplication id="com.ibm.mq.console"> tags.
- To assign roles and grant access to the REST API, add your users and groups between the appropriate security-role tags within the <enterpriseApplication id="com.ibm.mq.rest"> tags.
For help with the format of the user and group information within the security-role tags, see the example.
If you provided passwords for users in mqwebuser.xml, you should encode these passwords, to make them more secure, by using the securityUtility encoding command provided by WebSphere Application Server Liberty. For more information, see Liberty:securityUtility command in the WebSphere Application Server Liberty product documentation.

Example

In the following example, the group MQWebAdminGroup is granted access to the IBM MQ Console with the role MQWebAdmin. The user, reader, is granted access with the role MQWebAdminRO, and the user guest is granted access with the role MQWebUser:

<enterpriseApplication id="com.ibm.mq.console">
        <application-bnd>
            <security-role name="MQWebAdmin">
                <group name="MQWebAdminGroup" realm="defaultRealm"/>
            </security-role>
            <security-role name="MQWebAdminRO">
                <user name="reader" realm="defaultRealm"/>
            </security-role>
            <security-role name="MQWebUser">
                <user name="guest" realm="defaultRealm"/>
            </security-role>
        </application-bnd>
    </enterpriseApplication>

In the following example, the users reader and guest are granted access to the IBM MQ Console. The user user is granted access to the REST API, and any users within the MQAdmin group are granted access to the IBM MQ Console and the REST API:

<enterpriseApplication id="com.ibm.mq.console">
    <application-bnd>
        <security-role name="MQWebAdmin">
            <group name="MQAdmin" realm="defaultRealm"/>
        </security-role>
        <security-role name="MQWebAdminRO">
            <user name="reader" realm="defaultRealm"/>
        </security-role>
        <security-role name="MQWebUser">
            <user name="guest" realm="defaultRealm"/>
        </security-role>
    </application-bnd>
</enterpriseApplication>

<enterpriseApplication id="com.ibm.mq.rest">
    <application-bnd>
        <security-role name="MQWebAdmin">
            <group name="MQAdmin" realm="defaultRealm"/>
        </security-role>
        <security-role name="MQWebUser">
            <user name="user" realm="defaultRealm"/>
        </security-role>
     </application-bnd>
</enterpriseApplication>

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, you must use a secure connection. That is, you 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 for IBM MQ Version 9.0.4 and earlier. We can 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 REST API, but uses the client certificate instead. For more information, see Use client certificate authentication with the REST API and IBM MQ Console.