IBM MQ 9.0.2 expanded the capability of the Administrative REST API capability added in IBM MQ 9.0.1, this is detailed in recent blogs by my colleagues Mark Bluemel and Harvey Elsom. For a REST API to be genuinely useful, not only should the API offer a flexible and wide range of capabilities but it must have a robust security model. In this blog, I'll discuss some of the security features that are used by the IBM MQ REST API to authenticate a request and how these can be configured.
Authentication
Security configuration for the REST API uses the same configuration files as used by the IBM MQ Console, the "mqwebuser.xml" is used to configure the user registries and assignment of roles in exactly the same way. Authentication for requests to the REST API is for the most part common with the IBM MQ Console, however there are some additional options that are more suitable for programmatic API access. The IBM MQ REST API offers three different ways of authenticating REST API requests, these are;
HTTP Basic Authentication
Each HTTP request header carries an Base64 encoded version of a concatenation of the username and password to authenticate the request. Here is an example of a HTTP header that provides an Base64 encoded version of admin:admin;
Authorization: Basic YWRtaW46YWRtaW4=
This type of authentication might best be suited to use cases where periodic isolated requests need to be submitted - for example a web application that just reports on the state of a queue manager or a one-off command line request using curl. Many web tools, including curl provide the ability to provide credentials using HTTP basic authentication - here is an example of providing the username and password credentials via a curl command line;
curl "https://myhost.com:9443/ibmmq/rest/v1/installation" -X GET -u admin:admin
The basic authentication capability is not enabled by default, it needs to be enabled by using the basicAuthentication feature by adding the following to the "mqwebuser.xml";
<featureManager>
<feature>basicAuthenticationMQ-1.0</feature>
</featureManager>
X.509 Certificate
A certificate supplied by the client in the HTTPS handshake is used to authenticate all REST API requests, this works in exactly the same way as the IBM MQ Console. Here is an example of providing a certificate to use, using the curl command line.
curl -k https://myhost.com:9443/ibmmq/rest/v1/login --cert-type P12 --cert /home/joeblogger.p12:password -c /home/joeblogger/mycookies
Login / Security Token
A login URI is provided to submit username and password credentials via a HTTP POST request using JSON payload, if the verification of the credentials is successful, an LTPA (Lightweight Third Party Authentication) security token is returned as an cookie. The cookie must be supplied on subsequent REST requests as authentication instead of submitting a username and password. This type of authentication, whilst may be debatable by purists whether it is truly RESTful, offers a convenient way for browsers and web enabled applications that are likely to send multiple REST API requests to authenticate.
Here is an example of a POST to the login URI using the curl command line - note the use of -c and -b to provide a cookie jar;
curl "https://myhost.com:9443/ibmmq/rest/v1/login" -X POST -H “Content-Type: application/json” --data '{“username”:”admin”,“password”:”admin”}' -c /home/joeblogger/mycookies -b /home/joeblogger/mycookies
Once the login URI has been POST'ed successfully, the returned cookies can then be used on subsequent REST API requests - for example inquiring the installation;
curl "https://myhost.com:9443/ibmmq/rest/v1/installation" -X GET -c /home/joeblogger/mycookies -b /home/joeblogger/mycookies
In all cases, whilst HTTP can be enabled, the use of HTTPS is essential to prevent credentials and tokens being leaked and compromised.
Role based access control
You may already be aware that the IBM MQ Console uses RBAC (role based access control) to apply access restrictions to different authenticated users/principals, more details can be found in my previous blog here. The IBM MQ Console and REST API use the same three roles; MQWebAdmin, MQWebAdminRO and MQWebUser to provide different levels of access to administrative operations. As a recap;
MQWebAdmin
The most powerful role, allows all operations to be attempted under the security context of the application server.
MQWebAdminRO
As per MQWebAdmin, allows operations to be attempted under the security context of the application server - however this is restricted to read-only operations.
MQWebUser
This role allows any operation to be attempted under the security context of the request.
My REST API Request failed with a 401 or 403 response, why ?
An MQ REST API request that fails with a 401 error is indicating that the request is unauthenticated, for example credentials have been omitted or the verification process failed, for example due to a bad password. If a request fails with a response code of 403, this is indicating that the request was authenticated but the authenticated principal lacks access to the request resource. An example of a 403 response might be a MQWebUser trying to inquire a queue manager resource that they have not been granted OAM authority to.
In any unsuccessful REST API request, the response body will contain a JSON payload that contains further information on the failure.
Was the REST API request intentional ?
Browsers and other web enabled applications will generally cache credentials such as cookies and basic authentication to be used on subsequent requests to the same domain. Whilst in many cases this is a very useful behavior it can lead to a scenario where the credentials may be used unintentionally to submit a REST request - whilst inquiring the details of an installation might be harmless, clearly other types of request such as deleting a queue might be more worrying !
IBM MQ provides a cookie to header token countermeasure to prevent CSRF (Cross site request forgery), in my next blog I'll cover both this and support for CORS (Cross-origin resource sharing) in more detail.
