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_DIRECTORY/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_DIRECTORY/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:

      <sslDefault sslRef="mqDefaultSSLConfig"/>

      line from mqwebuser.xml.
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. The required contents of this header varies depending on the version of IBM MQ.

     For IBM MQ 9.0.4 and earlier, calculate the value of the ibm-mq-rest-csrf-token HTTP header by:

     1. Generating a CSRF token cookie, by submitting an HTTP GET request on the login REST API resource. Use the client certificate to authenticate the request.
     2. Setting the value of the ibm-mq-csrf-token header to the value of the CSRF token cookie, csrfToken, that is returned by the request.

        Note that you cannot use a cached version of the content of the cookie, because the content of the cookie can change. You must use the latest value of the cookie for each request.

     For IBM MQ 9.0.5 and later, set the value of the ibm-mq-csrf-token header to anything including blank. The header needs to be set in the request, but its value is not checked.

     Then, in both cases, submit the request.

Example

Important: In the example, not all cURL implementations support self signed certificates, so you must use a curl that does.

The following cURL example shows how to create a new queue Q1, on queue manager QM1, with client certificate authentication. The exact configuration of this cURL command depends on the libraries that cURL was built against. The example is based on a Windows system, with cURL built against OpenSSL:

• From IBM MQ 9.0.5, you only need to issue a single HTTP request. Use the HTTP POST method with the queue resource, authenticating with the client certificate and including the ibm-mq-rest-csrf-token HTTP header with an arbitrary value. This value can be anything, or blank; it is not checked by the mqweb server.
  IBM MQ 9.0.5 and later:

  curl -k https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue -X POST -
  -cert-type P12 --cert c:\user.p12:password 
  -H "ibm-mq-rest-csrf-token: value" 
  -H "Content-Type: application/json" --data "{\"name\":\"Q1\"}"
  

• For IBM MQ 9.0.4 and earlier two HTTP requests are needed:
  1. The first request generates the CSRF token cookie.
     Use the HTTP GET method with the login resource, authenticating with the client certificate. The CSRF token that is returned is stored within the cookiejar.txt file. The --cert-type1 flag specifies that the certificate is a PKCS#12 certificate. The --cert flag specifies the location of the certificate, followed by a colon, : , and then the password for the certificate. The -c flag specifies the location of the file to store the CSRF token in:

     curl -k https://localhost:9443/ibmmq/rest/v1/login --cert-type P12 --cert c:\user.p12:password -c c:\cookiejar.txt

  2. The second request creates the queue.

     Use the HTTP POST method with the queue resource, authenticating with the client certificate and including the contents of the CSRF token in a header:

     IBM MQ 9.0.3 and earlier:

     curl -k https://localhost:9443/ibmmq/rest/v1/qmgr/QM1/queue -X POST --cert-type P12 --cert c:\user.p12:password 
     -H "ibm-mq-rest-csrf-token: A6E85DE02E15EEAD2DBE49C0BCD6F191A7FA9535A161A4B7F019F2DE4625A8A5D24191E2409D2011F8700
     8E28786BD4E0ABD202B26C89360E8DA1F77CE737167A08E54AAB7C932CED1CF040E1F83C1D87F49C50BE724803A1642DB23FDF959CAA27B12
     A5BE36259FC2D9F92199B8AFFE886670EE454BD4B14A32C8A24E574F1FA0F251686B3670ED24F301615FC417BD40457CFCC92AC15C1A1C567
     3BCBB43963598FA9A1A77D91F53861290B0598AADD04591CEFBD18D6D55BB157A4F67FDB4D203AD42EB82799AC61CA0071417446C9E47A982
     099C0331AE4F3CD9C2F1611FC5FB122CE3C0F0A60AAC166EF98DE19234A524265391F9BF5496695EEAFED847" 
     -H "Content-Type: application/json" --data "{\"name\":\"Q1\"}"