Access IBM Sterling Order Management-hosted MQ server using IBM MQ client

IBM supports the IBM MQ-based integration to integrate IBM Sterling Order Management with any external third-party system.

The access to IBM MQ server within IBM Sterling Order Management environment is configured by using mutual authentication. The IBM MQ server is secured with Digicert Signed CA certificate and Client Authentication. Client Authentication allows users to securely access any services from a server by exchanging digital certificates.

To connect IBM MQ server from any external IBM MQ client, configure the client with an SSL/TLS IBM MQ certificates that is generated by using the Self Service tool, along with the trusted DigiCert Root.

Learning objectives

This tutorial demonstrates how to test the client connectivity by using IBM MQ client for MQ-based integration between IBM Sterling Order Management and any external system over SSL.

Prerequisites

Download and install the IBM MQ client on an external system. You can download the IBM MQ client version 9.3.0, 9.2.5, or complete steps 1 to 3 provided in the Get an IBM MQ queue for development on Ubuntu tutorial.

After installation is successful, run /opt/mqm/bin/dspmqver and verify the IBM MQ client version.

[root@vilifies1 mqm]# /opt/mqm/bin/dspmqver
Name:        IBM MQ
Version:     9.2.3.0
Level:       p923-L210708
BuildType:   IKAP - (Production)
Platform:    IBM MQ for Linux (x86-64 platform)
Mode:        64-bit
O/S:         Linux 4.18.0-372.32.1.el8_6.x86_64
O/S Details: Red Hat Enterprise Linux 8.7 (Ootpa)
InstName:    Installation1
InstDesc:
Primary:     No
InstPath:    /opt/mqm
DataPath:    /var/mqm
MaxCmdLevel: 923
LicenseType: Production
[root@vilifies1 mqm]#

We will be referencing the following filenames and directory paths. If you change any of these values, make sure to replace them before executing any of the commands listed in this tutorial:

• IBM MQ installation directory: /opt/mqm/
• Directory to store SSL certificate and key repository: /opt/mqm/certs/
• IBM MQ client certificate label used: owner=shoebvb,platform=sandbox
• IBM MQ client certificate filename used: owner=shoebvb,platform=sandbox.p12
• IBM MQ Server hostname: <tenant_code>-<env>-<envno>-mq.oms.supply-chain.ibm.com

For example, if tenant code is betap, the host is betap-dev-1-mq.oms.supply-chain.ibm.com.

Estimated time

This tutorial takes about one hour.

Steps

Step 1. Set up a key repository by running the runmqakm (GSKCapiCmd) command

1. Obtain the client certificate for IBM MQ from the Self Service tool. For more information about generating inbound certificates, see Inbound certificates.
   a. Generate the certificate. b. Apply your changes. c. Wait for the update IBM MQ server certification process to complete. d. Download the newly created certificate. Here, keydbpass is used as the password. e. Transfer the p12 file to the IBM MQ client machine. You can find certificates in the /opt/mqm/certs/ directory.

   cd /opt/mqm/certs/
   ls
   

   Expected output:

   owner=shoebvb,platform=sandbox.p12
   

2. Download the DigiCert High Assurance EV Root CA PEM certificate from DigiCert Trusted Root Authority Certificates:

   wget https://cacerts.digicert.com/DigiCertHighAssuranceEVRootCA.crt.pem
   ls
   

   Expected output:

   DigiCertHighAssuranceEVRootCA.crt.pem 'owner=shoebvb,platform=sandbox.p12'
   

3. Create the key repository and import both MQ certificates and DigiCert by running the following commands:

   cd /opt/mqm/certs/
   /opt/mqm/bin/runmqakm -keydb -create -db key.kdb -pw keydbpass -type cms -expire 365 -stash
   /opt/mqm/bin/runmqakm -cert -add -db key.kdb -label ibmwebspheremq_om_qmgr -file DigiCertHighAssuranceEVRootCA.crt.pem -pw keydbpass
   /opt/mqm/bin/runmqakm -cert -import -file owner\=shoebvb\,platform\=sandbox.p12 -type pkcs12 -pw keydbpass -target key.kdb -target_pw keydbpass
   /opt/mqm/bin/runmqakm -cert -list personal -db key.kdb -pw keydbpass
   

   Expected output:
   

   Certificates found
   * default, - personal, ! trusted, # secret key
   - owner=shoebvb,platform=sandbox
   

For more information about the runmqakm command, see Setting up a key repository on AIX, Linux, and Windows.

Note: To ease the installation process, the same keydbpass password is used for both certificate and key repository.

Step 2. Create a test queue by using the Self Service tool

1. Create a queue with name OMS_SANDBOX_DEMO. Wait for the process to complete.
2. Post the sample message by using the Self Service tool. Wait for the process to complete.

Step 3. Configure the IBM MQ client

1. Export the environment variables:
   

   export MQCHLLIB=/var/mqm/
   export MQCHLTAB=AMQCLCHL.TAB
   export MQSSLKEYR=/opt/mqm/certs/key
   export LD_LIBRARY_PATH=/opt/mqm/lib64
   export DYLD_LIBRARY_PATH=/opt/mqm/lib64
   

   Run the following command with the environment variable to list certificates from the key repository:
   

   cd /opt/mqm/bin/
   runmqakm -cert -list -db $MQSSLKEYR.kdb -pw keydbpass
   

   Expected output:
   

   Certificates found
   * default, - personal, ! trusted, # secret key
   !    ibmwebspheremq_om_qmgr
   -    owner=shoebvb,platform=sandbox
   

2. Edit the mqclient.ini file and add OutboundSNI under SSL stanza:
   

   SSL:
    OutboundSNI=HOSTNAME
   

   Note: For IBM MQ client, version 9.2.1 and earlier, set AllowOutboundSNI to NO. This provides the same function as OutboundSNI that is set to HOSTNAME.
   

3. Create a channel definition, which generates the AMQCLCHL.TAB file:

   cd /opt/mqm/bin/
   runmqsc -n
   DEFINE CHANNEL(SYSTEM.TLS.SVRCONN) CHLTYPE(CLNTCONN) TRPTYPE(TCP) CONNAME('<tenant_code>-<env>-<envno>-mq.oms.supply-chain.ibm.com(15443)') QMNAME(OM_QMGR) SSLCIPH('ECDHE_RSA_AES_128_GCM_SHA256') CERTLABL('owner=shoebvb,platform=sandbox')
   end
   

   Expected output:
   

   /opt/mqm/bin/runmqsc -n
   5724-H72 (C) Copyright IBM Corp. 1994, 2021.
   Starting local MQSC for 'AMQCLCHL.TAB'.
   
   DEFINE CHANNEL(SYSTEM.TLS.SVRCONN) CHLTYPE(CLNTCONN) TRPTYPE(TCP) CONNAME('<tenant_code>-<env>-<envno>-mq.oms.supply-chain.ibm.com(15443)') QMNAME(OM_QMGR)   SSLCIPH('ECDHE_RSA_AES_128_GCM_SHA256') CERTLABL('owner=shoebvb,platform=sandbox')
       1 : DEFINE CHANNEL(SYSTEM.TLS.SVRCONN) CHLTYPE(CLNTCONN) TRPTYPE(TCP) CONNAME('<tenant_code>-<env>-<envno>-mq.oms.supply-chain.ibm.com(15443)') QMNAME(OM_QMGR)   SSLCIPH('ECDHE_RSA_AES_128_GCM_SHA256') CERTLABL('owner=shoebvb,platform=sandbox')
   AMQ8014I: IBM MQ channel created.
   end
       2 : end
   No commands have a syntax error.
   

Step 4. Validation

Get a test message from the OMS_SANDBOX_DEMO queue (message posted in step 2):

cd /opt/mqm/samp/bin/
amqsgetc OMS_SANDBOX_DEMO OM_QMGR
Sample AMQSGET0 start
message <This is a test message>
Sample AMQSGET0 end

Additional commands

1. PUT the test messages (use IBM MQ client built in test program, execute a test PUT message):
   

   cd <MQClientInstallation>\bin
   amqsputc <TESTQUEUE> <OM_QMGR>
   
   Sample AMQSPUT0 start
   Target queue is <TESTQUEUE>
   <type message here>
   <enter>
   <enter>
   Sample AMQSPUT0 end
   

2. GET test messages (removes from the queue):
   

   cd <MQClientInstallation>\bin
   amqsgetc <TESTQUEUE> <OM_QMGR>
   
   Sample AMQSGET0 start
   <the messages will be displayed here, one by one>
   <enter>
   <enter>
   Sample AMQSGET0 end
   

3. List the queue depth:
   

   ccd <MQClientInstallation>\bin
   runmqsc -n
   
   DISPLAY QUEUE (TEST_QUEUE)
   

Summary

In this tutorial, we showed you how to test the client connectivity by using IBM MQ client for MQ-based integration between IBM Sterling Order Management and any external system over SSL. Learn more by checking out additional articles and tutorials in our IBM Sterling hub.