Configuring an LDAP registry for the IBM MQ Console and REST API

You can configure an LDAP registry within the mqwebuser.xml file. The user names and passwords in the LDAP registry are used to authenticate and authorize users of the IBM® MQ Console and the REST API.

Before you begin

When you configure an LDAP registry, you must assign each user a role. Each role provides different levels of privilege to access the IBM MQ Console and REST API, and determines the security context that is used when an allowed operation is attempted. You need to understand these roles before you configure the registry. For more information about each of the roles, see Roles on the IBM MQ Console and REST API.
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.
To complete this task, you must be a user with sufficient privileges to edit the mqwebuser.xml file:
- On z/OS®, you must have write access to the mqwebuser.xml file.
- On all other operating systems, you must be a privileged user.
- If the mqweb server is part of a stand-alone IBM MQ Web Server installation, you must have write access to the mqwebuser.xml file in the IBM MQ Web Server data directory.

Procedure

Copy the sample XML file ldap_registry.xml from one of the following paths:
- In an IBM MQ installation:
  - On AIX®, Linux®, and Windows: MQ_INSTALLATION_PATH /web/mq/samp/configuration
  - On z/OS: PathPrefix /web/mq/samp/configuration
    where PathPrefix is the IBM MQ for z/OS UNIX System Services Components installation path.
- In a stand-alone IBM MQ Web Server installation: MQWEB_INSTALLATION_PATH/web/mq/samp/configuration
  where MQWEB_INSTALLATION_PATH is the directory to which the IBM MQ Web Server installation file was decompressed.
Place the sample file in the appropriate directory:
- In an IBM MQ installation:
  - On AIX or Linux: /var/mqm/web/installations/installationName/servers/mqweb
  - On Windows: MQ_DATA_PATH\web\installations\installationName\servers\mqweb, where MQ_DATA_PATH is the IBM MQ data path. This path is the data path that is selected during the installation of IBM MQ. By default, this path is C:\ProgramData\IBM\MQ.
  - 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.
- In a stand-alone IBM MQ Web Server installation: MQ_OVERRIDE_DATA_PATH/web/installations/MQWEBINST/servers/mqweb
  where MQ_OVERRIDE_DATA_PATH is the IBM MQ Web Server data directory that the MQ_OVERRIDE_DATA_PATH environment variable points to.
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 change the LDAP registry settings within the ldapRegistry and idsLdapFilterProperties tags.

For more information about configuring LDAP registries, see Configuring LDAP user registries in Liberty in the WebSphere® Liberty documentation.
Assign roles to users and groups by editing the mqwebuser.xml file:
There are several 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.

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 you can optionally configure the expiry interval for the LTPA token. For more information, see Configuring 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 Configuring 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 Using 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 Using token-based authentication with the REST API. You can configure the expiry interval for the LTPA token. For more information, see Configuring 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 Configuring client certificate authentication with the REST API and IBM MQ Console.