Configure TLS for the REST API and IBM MQ Console on z/OS

On z/OS, we can configure the mqweb server to use a RACF key ring to store certificates for secure connections with TLS, and client certificate authentication.

Before starting

The default mqweb server configuration uses Java keystores for the server and trusted certificates. On z/OS, we can configure the mqweb server to use a RACF key ring, instead of the Java keystores. The server can also be configured to allow users to authenticate using a client certificate.

See Liberty: Keystores for information on using RACF key rings in Liberty.

Follow this procedure to configure the mqweb server to use a RACF key ring, and optionally configure client certificate authentication. This procedure describes the steps necessary to create and use certificates signed with your own certificate authority (CA) certificates. For production, you might prefer to use certificates obtained from an external certificate authority.

Procedure

1. Create a certificate authority (CA) certificate, which will be used to sign the server certificate. For example, enter the following RACF command:

   RACDCERT GENCERT -
     CERTAUTH -
     SUBJECTSDN(CN('mqweb Certification Authority') -
       O('IBM') -
       OU('MQ')) -
     SIZE(2048) -
     WITHLABEL('mqwebCertauth')

2. Create a server certificate, signed with the CA certificate created in step 1, by entering the following command:

   RACDCERT ID(mqwebUserId) GENCERT -
     SUBJECTSDN(CN('hostname') -
      O('IBM') -
      OU('MQ')) -
      SIZE(2048) -
      SIGNWITH (CERTAUTH LABEL('mqwebCertauth')) -
     WITHLABEL('mqwebServerCert')

   where mqwebUserId is the mqweb server started task user ID, and hostname is the host name of the mqweb server.
3. Connect the CA certificate and server certificate to a SAF key ring by entering the following commands:

   RACDCERT ID(mqwebUserId) CONNECT(RING(keyring) LABEL('mqwebCertauth') CERTAUTH)
   RACDCERT ID(mqwebUserId) CONNECT(RING(keyring) LABEL('mqwebServerCert'))

   where mqwebUserId is the mqweb server started task user ID, and keyring is the name of the key ring we want to use.
4. Export the CA certificate to a CER file by entering the following command:

   RACDCERT CERTAUTH EXPORT(LABEL('mqwebCertauth')) -
           DSN('hlq.CERT.MQWEBCA') -
           FORMAT(CERTDER) -
           PASSWORD('password')

5. FTP the exported CA certificate in binary to your workstation, and import it into your browser as a certificate authority certificate.
6. Optional: To configure client certificate authentication, create and export a client certificate.
   1. Create a certificate authority (CA) certificate, which will be used to sign the client certificate. For example, enter the following RACF command:

      RACDCERT GENCERT -
        CERTAUTH -
        SUBJECTSDN(CN('mqweb User CA') -
         O('IBM') -
         OU('MQ')) -
         SIZE(2048) -
        WITHLABEL('mqwebUserCertauth')

   2. Connect the CA certificate to a SAF key ring by entering the following command:

      RACDCERT ID(mqwebUserId) CONNECT(RING(keyring) LABEL('mqwebUserCertauth') CERTAUTH)

      where mqwebUserId is the mqweb server started task user ID, and keyring is the name of the key ring we want to use.
   3. Create a client certificate, signed with the CA certificate. For example, enter the following command:

      RACDCERT ID(clientUserId) GENCERT -
        SUBJECTSDN(CN('clientUserId') -
           O('IBM') -
           OU('MQ')) -
         SIZE(2048) -
         SIGNWITH (CERTAUTH LABEL('mqwebUserCertauth')) -
        WITHLABEL('userCertLabel')

      where clientUserId is the user name. The method used to map a certificate to a principal depends on the type of user registry configured:
      • If we are using a basic registry, the Common Name field in the certificate is matched against the user in the registry.
      • If we are using a SAF registry, and the certificate is in the RACF database, the certificate owner, specified with the ID parameter when creating the certificate, is used.
      • If we are using an LDAP registry, the full distinguished name in the certificate is matched against the LDAP registry.

   4. Export the client certificate to a PKCS #12 file by entering the following command:

      RACDCERT ID(mqwebUserId) EXPORT(LABEL('userCertLabel')) -
               PASSWORD('password') DSN('hlq.USER.CERT')

   5. FTP the exported certificate in binary to your workstation. To use the client certificate with the IBM MQ Console, import it into the web browser used to access the IBM MQ Console as a personal certificate.

7. Edit the file WLP_user_directory/servers/mqweb/mqwebuser.xml, where WLP_user_directory is the directory that was specified when the crtmqweb script ran to create the mqweb server definition. Make the following changes to configure the mqweb server to use a RACF key ring:
   1. Remove, or comment out, the following line:

      <sslDefault sslRef="mqDefaultSSLConfig"/>

   2. Add the following statements:

      <keyStore id="defaultKeyStore" filebased="false"
                location="safkeyring://mqwebUserId/keyring"
                password="password" readOnly="true" type="JCERACFKS" />
      <ssl id="thisSSLConfig" keyStoreRef="defaultKeyStore" sslProtocol="TLSv1.2"
                serverKeyAlias="mqwebServerCert" clientAuthenticationSupported="true" />
      <sslDefault sslRef="thisSSLConfig"/>

      where:
      • mqwebUserId is the mqweb server started task user ID.
      • keyring is the name of the RACF key ring.
      • mqwebServerCert is the label of the mqweb server certificate.

      Notes: The value of keyStore password is ignored.

8. Restart the mqweb server by stopping and restarting the mqweb server started task.
9. Optional: Use the client certificate to authenticate:
   • To use the client certificate with the IBM MQ Console, enter the URL for the MQ Console in the web browser where you installed the client certificate.
   • To use the client certificate with the REST API, provide the client certificate with each REST request.

   Notes:

   1. If we are using only certificates to authenticate to the IBM MQ Console, the browser might display a list of certificates for you to select from.
   2. To use a different certificate you might need to close and restart your browser.
   3. If we are using client certificates that are not in the RACF database, we can use RACF certificate name filtering, to map certificate attributes to a user ID. For example:

      RACDCERT ID(DEPT3USR) MAP SDNFILTER(OU=DEPT1.C=US)

      maps certificates with a subject distinguished name containing OU=DEPT1 and C=US to user ID DEPT3USR.

Results

We have set up a TLS interface for the IBM MQ Console and REST API.