Using client certificate authentication with the REST API and IBM MQ Console

You can map client certificates to principals to authenticate IBM® MQ Console and REST API users.

1. Start the mqweb server by entering the strmqweb command on the command line.
2. Create a client certificate:
   1. Create a PKCS#12 keystore:
      1. Open the IBM Key Management tool by entering the strmqikm command on the command line.
      2. From the Key Database File menu in the IBM Key Management tool, click New.
      3. Select PKCS12 from the Key database type list.
      4. Select a location to save the keystore, and enter an appropriate name in the File Name field. For example, user.p12
      5. Set a password when prompted.
   2. Create the certificate, either by creating a self-signed certificate, or by obtaining a certificate from a certificate authority:
      • Create a self-signed certificate:
        1. Click New Self-Signed.
        2. Enter user in the Key Label field.
        3. If you are using a basic user registry, enter the name of a user from your user registry in the Common Name field. For example, mqadmin. For an LDAP user registry, make sure that the distinguished name for the certificate matches the distinguished name in the LDAP registry.
        4. Click OK.
      • Obtain a certificate from a certificate authority. The CA certificate must include the appropriate user name within the common name (CN) of the distinguished name (DN) field:
        1. Request a new certificate. From the Create menu, click New Certificate Request.
        2. In the Key Label field, enter the certificate label.

        3. If you are using a basic user registry, in the Common Name field, enter the user name of the user that the certificate is for.

           If you are using a local OS registry, the Common Name field must match the local OS user id.

           For an LDAP user registry, make sure that the distinguished name for the certificate matches the distinguished name in the LDAP registry.

        4. Type or select values for the remaining fields, as applicable.
        5. Choose where to save the certificate request, and the filename for the certificate request, then click OK.
        6. Send the certificate request file to a certificate authority (CA).
        7. When you have the certificate from the CA, open the IBM Key Management tool by entering the strmqikm command on the command line.
        8. From the Key Database File menu in the IBM Key Management tool, click Open.
        9. Select the PKCS#12 keystore that holds the client certificate. For example, user.p12
        10. Click Receive, select the appropriate certificate, and click OK.
3. Extract the public part of the client certificate:
   1. Open the IBM Key Management tool by entering the strmqikm command on the command line.
   2. From the Key Database File menu in the IBM Key Management tool, click Open.
   3. Select the PKCS#12 keystore that holds the client certificate. For example, user.p12
   4. Select the client certificate from the certificate list in the IBM Key Management tool.
   5. Click Extract Certificate.
   6. Select a location to save the certificate, and enter an appropriate file name in the Certificate file name field. For example, user.arm.
4. Import the public part of the client certificate into the mqweb server trust keystore as a signer certificate so that the server can validate the client certificate:
   1. Create a trust.jks keystore for use by the mqweb server, if one does not already exist:
      1. From the Key Database File menu in the IBM Key Management tool, click New.
      2. Select JKS from the Key database type list.
      3. Click Browse and navigate to: MQ_DATA_DIRECTORY/web/installations/installationName/servers/mqweb/resources/security.

         This directory should already contain a key.jks file. If a trust.jks file already exists then open the existing one rather than overwriting it.

      4. Enter trust.jks in the File Name field.
      5. Set a password when prompted.
   2. From the drop-down menu, select Signer Certificates.
   3. Click Add.
   4. Select the appropriate arm file, and click OK. For example, select user.arm.
   5. Enter a label for the certificate.
5. Change the password of the mqweb server keystore:
   1. From the Key Database File menu, click Open.
   2. Select JKS from the Key database type list.
   3. Click Browse and navigate to MQ_DATA_PATH/web/installations/installationName/servers/mqweb/resources/security
   4. Select the key.jks keystore, and click Open.
   5. Enter the password when prompted. The default password is password.
   6. From the Key Database File menu, click Change Password.
   7. Enter a new password for the keystore.
6. Enable client certificate authentication in the mqwebuser.xml file:

   The mqwebuser.xml file can be found on the following path: MQ_DATA_PATH/web/installations/installationName/servers/mqweb

   1. Uncomment the section in the mqwebuser.xml file that enables client certificate authentication. The section contains the following text:

      <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"/>

   2. Check that the serverKeyAlias value matches the name of the server certificate. If you are using the default server certificate, the value is correct.
   3. Change the value for password for the defaultKeyStore to an encoded version of the password for the key.jks keystore:
      1. From the MQ_INSTALLATION_PATH/web/bin directory, enter the following command on the command line:

         securityUtility encode password

      2. Place the output of this command in the password field for the defaultKeyStore.
   4. Change the value for password for the defaultTrustStore to match the password for the trust.jks keystore:
      1. From the MQ_INSTALLATION_PATH/web/bin directory, enter the following command on the command line:

         securityUtility encode password

      2. Place the output of this command in the password field for the defaultTrustStore.
   5. Remove, or comment out, the following line from the mqwebuser.xml file:

      <sslDefault sslRef="mqDefaultSSLConfig"/>

7. Stop the mqweb server by entering the endmqweb command on the command line.
8. Start the mqweb server by entering the strmqweb command on the command line.
9. Use the client certificate to authenticate:
   • To use the client certificate with the IBM MQ Console, install the client certificate into the web browser that is used to access the IBM MQ Console. For example, install the client certificate user.p12 as a personal certificate.
   • To use the client certificate with the REST API, provide the client certificate with each REST request. When you use HTTP POST, PATCH, or DELETE methods, you must provide extra authentication with the client certificate to prevent cross-site request forgery attacks. That is, the extra authentication is used to confirm that the credentials that are being used to authenticate the request are being used by the owner of the credentials.

     This extra authentication is provided by the ibm-mq-rest-csrf-token HTTP header. Set the value of the ibm-mq-csrf-token header to anything including blank, then submit the request.