IBM MQ Console and REST API security

Security for the IBM MQ Console and the REST API is configured by editing the mqweb server configuration in the mqwebuser.xml file.

About this task

We can track user actions and audit the use of the IBM MQ Console and the REST API by examining the log files of the mqweb server.

Users of the IBM MQ Console and the REST API can be authenticated by using:

• Basic registry
• LDAP registry
• Local OS registry
• SAF on z/OS
• Any other registry type supported by WebSphere Liberty

Roles can be assigned to IBM MQ Console users, and to REST API users to determine what level of access they are granted to IBM MQ objects. For example, to perform messaging, users must be assigned the MQWebUser role. For more information about the available roles, see Roles on the IBM MQ Console and REST API.

After a user is assigned a role, there are a number of methods that can be used to authenticate the user. With the IBM MQ Console, users can log in with a user name and password, or can use client certificate authentication. With the REST API, users can use basic HTTP authentication, token based authentication, or client certificate authentication.

Procedure

1. Define the user registry to authenticate users, and assign each user or group a role to authorize the users and groups to use the IBM MQ Console or REST API. For more information, see Configure users and roles
2. Choose how users of the IBM MQ Console authenticate with the mqweb server. You do not have to use the same method for all users:
   • 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 time 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.

3. Choose how users of the REST API authenticate with the mqweb server. You do not have to use the same method for all users:
   • 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.

     In order for this authentication to be secure, we must use a secure connection. That is, we must use HTTPS. However, if you have enabled HTTP connections, you can allow an LTPA token that is issued for an HTTPS connection to be used for an HTTP connection. 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.

4. Optional: Configure Cross Origin Resource Sharing for the REST API.

   By default, a web browser does not allow scripts, such as JavaScript, to invoke the REST API when the script is not from the same origin as the REST API. That is, cross-origin requests are not enabled. We can configure Cross Origin Resource Sharing (CORS) to allow cross-origin requests from specified URLs. For more information, see Configure CORS for the REST API.

5. Optional: Configure host header validation for the IBM MQ Console and REST API.

   We can configure host header validation and create an allowlist of hostnames and ports to ensure that only requests that contain specific host headers are processed by the IBM MQ Console and REST API. For more information, see Configure host header validation for the IBM MQ Console and REST API.

• 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.
• Use client certificate authentication with the REST API and IBM MQ Console
  We can map client certificates to principals to authenticate IBM MQ Console and REST API users.
• Use HTTP basic authentication with the REST API
  Users of the REST API can authenticate by providing their user ID and password within an HTTP header. To use this method of authentication with HTTP methods, such as POST, PATCH, and DELETE, the ibm-mq-rest-csrf-token HTTP header must also be provided, as well as a user ID and password.
• Use token-based authentication with the REST API
  Users of the REST API can authenticate by providing 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 authenticate future requests. This LTPA token has the prefix LtpaToken2. The user can log out by using the HTTP DELETE method, and can query the log in information of the current user with the HTTP GET method.
• Embedding the IBM MQ Console in an IFrame
  The HTML <iframe> element can be used to embed one web page into another using an Inline Frame (IFrame). For security reasons the IBM MQ Console can not be embedded into an IFrame by default. However, we can enable an IFrame by using the mqConsoleFrameAncestors configuration property on the mqweb server.
• Configure CORS for the REST API
  By default, a web browser does not allow scripts, such as JavaScript, to invoke the REST API when the script is not from the same origin as the REST API. That is, cross-origin requests are not enabled. We can configure Cross Origin Resource Sharing (CORS) to allow cross-origin requests from specified origins.
• 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.
• Auditing
  Audit records of operations performed in the IBM MQ Console and REST API can be produced by enabling queue manager command and configuration events, and on UNIX, Linux, and Windows significant state changes are recorded in the log files of the mqweb server.
• Security considerations for the IBM MQ Console and REST API on z/OS
  The IBM MQ Console and REST API have security features controlling whether a user can issue, display, or alter commands. The commands are then passed to the queue manager, and the queue manager security is then used to control if the user is allowed to issue the command to that specific queue manager.

Parent topic: Securing IBM MQ