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

A method of configuring TLS for the IBM MQ Console and REST API on z/OS®.

Before you begin

To configure the use of the TLS interface you need to specify statements in an XML file.

We can add them to the mqwebuser.xml file, or create a separate file, for example, ssl.xml and add a statement <include location="ssl.xml"/> at the bottom of the mqwebuser.xml file.

Procedure

1. In mqwebuser.xml, comment out the existing definitions for:
   • mqDefaultSSLConfig
   • defaultKeyStore
2. In mqwebuser.xml, add the following code statements:

   <?xml version="1.0" encoding="UTF-8"?>
   
   <server>
       <featureManager>
          <feature>ssl-1.0</feature>
      </featureManager>    
      <sslDefault sslRef="mqDefaultSSLConfig"/>
      <ssl id="mqDefaultSSLConfig" keyStoreRef="defaultKeyStore"
         sslProtocol="TLSv1.2"
         serverKeyAlias="def2"
         clientAuthentication="true"
       />
   
      <keyStore id="defaultKeyStore"
           filebased="false"
           location="safkeyring://userid/keyring"
           password="password"
           readOnly="true"
           type="JCERACFKS"
   />
   </server>
   

   Notes:
   1. The text in bold is required to define the TLS interface.
   2. The value of sslRef="mqDefaultSSLConfig" in sslDefault must match one of the <ssl id=...... values
   3. The value of <ssl keyStoreRef="defaultKeyStore" in <ssl must match the id= value in a <keystore.
   4. Specify the user ID, and the keyring of the user ID, to be used in the location="safkeyring://userid/keyring" statement.
   5. The value of serverKeyAlias ( for example, serverKeyAlias="def2") is the name of the certificate in the keyring to be used by the IBM MQ Console
   6. The value of keystore password is ignored.

   See Liberty: Keystores for RACF keyring information.

   RACF definitions

   With a value of:
   1. location="safkeyring://SCENSTC/MYKEYRING"
   2. serverKeyAlias="def2"
   the output of the RACF command RACDCERT LISTRING(MYKEYRING) ID(SCENSTC) is:

   Digital ring information for user SCENSTC:                
   
     Ring:   
          >MYKEYRING<  
     Certificate Label Name             Cert Owner     USAGE      DEFAULT
     --------------------------------   ------------   --------   ------- 
     SCENCA                             CERTAUTH       CERTAUTH     NO
     def2                               ID(SCENSTC)    PERSONAL     NO
   

   Note: If you are using self-signed certificates these need to be connected to the keyring.
3. Restart the mqweb server. There should be no messages in //STDERR

   There should be messages in //STDOUT similar to those listed in Get started with the IBM MQ Console..

   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 need to close and restart your browser.
   3. If you are using certificates that are not in the RACF database, we can use RACF certificate name filtering, to map attributes in the certificate to a user ID, for example:

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

      maps certificates with OU=DEPT1 and C=US to user ID DEPT3USR

Results

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