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

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

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 you 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: If you want 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 you 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 you are using a basic registry, the Common Name field in the certificate is matched against the user in the registry.
      • If you 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 you 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 you 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. If you want to use a different certificate you might need to close and restart your browser.
   3. If you are using client certificates that are not in the RACF database, you 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.