IBM MQ: Add a new java client to a queue manager that is using two-way TLS/SSL authentication

In my line of work this is quite common task. I’ll place it here to be able to point new colleagues to it when I get tired of explaining 🙂
I’m here going to use the runmqsc and ikeycmd, both shipped with MQ from 8 and up, and the keytool program that can be found in most java distributions. MQExplorer and ikeyman could also be used if you like a GUI better

Add client to OS

useradd client43

Set a password and we are done with the OS part

Now create client channel in MQ (runmqsc MYQM01)

DEFINE CHANNEL(CLIENT43) CHLTYPE(SVRCONN) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA) MCAUSER('client43') 

Two things to note here:
* MCAUSER: this is the OS user that is going to use the channel. In this case ‘client43’ that we created in the beginning
* SSLCIPH: this cipher has to match the one used in the client. NOTE! Cipher names can differ between Java and MQ. Search IBM website for translation tables between cipher names

Set connection access to the new client

 
setmqaut -m MYQM01 -t qmgr -p client43 -all +connect +inq

Set object access to the new client (eg. PUT and GET rights for a local queue)

setmqaut -m MYQM01 -t queue -n QL.MY.CLIENTS.NEW.QUEUE -p client43 -all +put +get
...

Add client certificate to MQ certificate store

ikeycmd -cert -add -db "/var/mqm/qmgrs/MYQM01/ssl/key.kdb" -pw changeit -label ibmwebspheremqclient43 -file ibmwebspheremqclient43.crt -format ascii  

NOTE: The default naming convention for client certificates is: ibmwebspheremq + user name. In this example it turns out to: ibmwebspheremqclient43

NOTE 2: If you are using a self-signed certificate you only need to add that certificate to the MQ certificate store BUT if you are using a CA signed client certificate ALL certificates need to be put into the MQ certificate store in order from root to client certificate. The whole certificate chain needs to be present for the client certificate to be resolved correctly by MQ

Add server certificate to the client.jks

keytool -import -alias ibmwebspheremqmyqm01 -file ibmwebspheremqmyqm01.crt -keystore client.jks

NOTE: You can use whatever label you want here. I use the default MQ naming pattern for anything relating to IBM MQ

Done!

Troubleshooting tips

# Test auth records towards client user 
DISPLAY CHLAUTH(CLIENT43) MATCH(RUNCHECK) ALL ADDRESS('127.0.0.1') CLNTUSER('client43')

# Check clients authentication records on the queue manager
dmpmqaut -m MYQM01 -p client43

# View certificate labels in jks 
keytool -list -keystore client.jks -storepass changeit

# View certificate labels in kdb
ikeycmd -cert -list ca -db key.kdb -pw changeit

Tested on MQ 9.0.5.0, Java 1.8.0_121 and Red Hat Linux 7.5

  1. I think you are using self-signed client certificates here? You’re not using a CA signed certificate? If you used a CA signed certificate then you wouldn’t need to add every client certificate to the queue manager KDB, you would just need the CA.

    Also, whichever way you do it, it may also be worth adding some DN checking to the SVRCONN (preferably using CHLAUTH) to ensure that the client can only connect through the appropriate channel. Without that, a client could accidentally come into a different channel and successfully connect and be granted inappropriate authorities because of the static MCAUSER set on the channel.

    Also, please note that the label ‘webspheremq’ is not required at the queue manager end, only at the client end. The queue manager does not look up the client certificate by label to validate it. The label is only used to locate the certificate that will be presented by a client (or QMgr) as its identity.

    • Niklas Ottosson

      If I don’t add the client certificate to the KBD would that not mean that anyone who got a certificate from the same CA (example GoDaddy) would be allowed to connect? I only want a particular client the possibility to connect, not all that has the same CA – I feel that I might be missing a piece of the puzzle here so you are very welcome to correct me.

      DN checking sounds like a great way to secure things even more – thanks for the tip!

      Yes that is true that you don’t need the ‘webspheremq’ label pattern in the client keystore – I will update my post

Leave a Comment


NOTE - You can use these HTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre lang="" line="" escaped="" cssfile="">

This site uses Akismet to reduce spam. Learn how your comment data is processed.