When a user logs into the IBM MQ web console, they generally do so by specifying a user id and a password in the login screen. However, it is possible to use a signed client certificate instead – once this has been set up, whenever the user accesses the console with the browser that has the certificate installed, they will automatically be logged into the console. This post gives a step-by-step guide to setting up client certificate authentication with the IBM MQ console to allow this. The use of a basic registry is assumed.

First, create a certificate that will be used to authenticate the user. The CN (common name) attribute of the distinguished name of the certificate is used to identify the user. For a production environment, a certificate should be obtained from a certificate authority – although a self-signed certificate can be used for convenience – the steps below describe this process. The certificate stores and certificates can be created using tools such as iKeyman. If you are not familiar with creating keystores and certificates, please use the details in this link with the steps below to create the required objects.

IBM Key Management Utility Documentation

  • Create a keystore of Key Database Type PKCS12
  • Create the self-signed certificate in this keystore. The CN (Common Name) attribute of this certificate should be the name of the user that will be specified in the user registry. For instance, if this attribute value is set to “certuser”, this is the name of the user that will be added to the console’s user registry. You will also need to copy the certificate store file created to some location from where this can later be added to your browser.
  • Extract the public part of the certificate, and save this extracted file – this will be used in the next step.
  • Create a truststore for the console server, if one does not exist. To do this go to the location:


    and create a new keystore of Key Database Type JKS.

  • Add the extracted public part of the certificate to this truststore as a signer certificate.

Enable client authentication in the mqwebuser.xml:

  • Open the file MQ_DATA_DIRECTORY/web/installations/installationName/servers/mqweb/mqwebuser.xml for editing, and add this text (or uncomment it if this is already there but commented out):

    <keyStore id="defaultKeyStore" location="key.jks" type="JKS" password="password"/>
    <keyStore id="defaultTrustStore" location="trust.jks" type="JKS" password="password"/>
    <ssl id="thisSSLConfig" clientAuthenticationSupported="true" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" sslProtocol="TLSv1.2" serverKeyAlias="default"/>
    <sslDefault sslRef="thisSSLConfig"/>

  • where the passwords are set for the key and trust stores – “password” is the default password for the keystore, and whatever was set for the truststore when this was created.
  • Remove or comment out the line:

    <sslDefault sslRef="mqDefaultSSLConfig"/>

  • Add the user as defined in the CN attribute of the certificate’s distinguished name to the user registry.

    For instance, add a user to the basicRegistry, and add this user to an appropriate group as defined for a security-role – here is an example:

    <basicRegistry id="basic" realm="defaultRealm">
    <user name="certuser" password="password"/>
    <group name="MQWebUI">
    <member name="certuser"/>

    Here the user’s “name” attribute must match the CN of the certificate – it does not matter what password is set for the purpose of this setup, as the password is not used when authenticating with a certificate. It is still possible to log into the console with this user name and password at the standard login screen however, so setting this to a secure password value is recommended.

    Then, locate the PKCS12 keystore containing the original self-signed certificate, and add this certificate to the browser – exactly how to do this varies by browser.

    Now, go to the console URL in the browser – there may be a pop-up where you have to select the certificate to use from the browser’s certificate store – then this will redirect to the console, without having to log in with the username and password at the login screen.

    Further reading:

    There is more detail on setting up console security and user roles in the Knowledge Centre:

    IBM MQ Console and REST API security
    Configuring users and roles
    Roles on the IBM MQ Console and REST API

Leave a Reply