webMethods on prem to IBM SaaS MQ - via MQ Adapter

Ragav1 · June 19, 2023, 9:12am

Existing on-premise setup

Currently our webMethods v10.3 IS integrates with IBM Sterling Order Management component via using IBM WebSphere MQ on-premise.
This setup is currently done via JNDI Bindings + JMS connections.

The on prem IBM Sterling Order Management (OMS) is migrating to SaaS platform.
Hence the on prem MQ setup needed to be migrated to the SAAS MQ platform.
The JNDI/JMS based connection setup cannot be used as IBM SAAS MQ doesn’t support this type of connection.
Hence the MQ Adapters used in on prem was tried to be used for this setup/connection.

ESB will connect with the IBM Sterling OMS MQ platform in SAAS to publish and subscribe to messages.

This connection is established using SoftwareAG webMethods WebSphere MQ Adapter v6.5.

The below points and steps will provide detail on how this connection has been established:

Latest version of this webMethods plugin will be installed in ESB Integration Server
- The latest version of the fix patch should also be installed for this adapter. - MQS_6.5_Fix50
This will co exist along with the on prem MQ connection to the webSphere MQ platform.

The on premise connection currently uses the below jars of version v7.5.0.5
- This is maintained in the Integration Server’s common library directory - /IntegrationServer/lib/jars/
- As part of the process, these jars are uplifted to v9.2.0.0
The MQ Adapter also requires the same set of jars that is required to connect to IBM
- This is maintained in the MQ Adapter code module: /IntegrationServer/instances/default/packages/WmMQAdapter/code/jars/
The latest version v9.2.0.0 of MQ JARS is placed in the above 2 locations to establish connections:
- com.ibm.mq.commonservices.jar
- com.ibm.mqjms.jar
- com.ibm.mq.pcf.jar
- com.ibm.mq.jmqi.jar
- com.ibm.mq.jar
- com.ibm.mq.headers.jar
- providerutil.jar
- jms.jar
- fscontext.jar
- Note: Please remove the com.ibm.mq.allclient-9.0.4.0.jar from /IntegrationServer/lib/jars/ as it is no longer required.
- The allclient jar supersedes all the above individual jars. So we cannot use both together which will not work.

As part of the connection the CIPHERS are required to be set up of ESB end for secured connection.
The CIPHER list in webMethods MQ adapter was enriched to support the latest versions required.
- The cipher ECDHE_RSA_AES_128_GCM_SHA256 is used this scenario.
- For exhaustive list of CIPHERS supported by IBM, refer to this link.
- Note: The underlying the JVM/JRE should support the latest version of this CIPHERS.
The NEW CIPHERS required need to be added into the configuration file inside WmMQAdapter package
- IntegrationServer/instances/default/packages/WmMQAdapter/config/config.xml

To establish the secure network the MQ Client Certificate and Root CA certificate both are required.
- The DigiCert High Assurance EV Root should be installed into the ESB Integration server’s trust store.
- MQ Client Certificate should be installed into the ESB Integration servers as a new key store.
- Both of the above certificates will be provided by IBM.
- The keystore and Trust store that needs to be used here is referenced in the custom_wrapper.conf file.
  - Location: /opt/webMethods/HostName/profiles/IS_default/configuration/customer_wrapper.conf file
Note: The new keystore password and the MQ client Certificate alias password inside the keystore should be the same.
Create the respective alias required via the IS Security > Keystore .
The same alias should be configured in the MQ Adapter connections.

In order to allow the CIPHERS via SSL the below JVM config needs to be set up in ESB Integration Server JVM/JRE suite.
- Dcom.ibm.mq.cfg.useIBMCipherMappings=false
- This is applicable for the non IBM JRE’s, particularly for Oracle JRE’s
For the SNI host name to be passed on during connection the below JVM config needs to be set up
- Dcom.ibm.mq.cfg.SSL.outboundSNI=NO
For the JMS/JNDI based connections to work alongside with WmMQAdapter please add the below config in custom_wrapper.conf file
- Dcom.ibm.mq.jms.SupportMQExtensions=true
The above parameters needs to be updated into the custom_wrapper.conf file
- Location: /opt/webMethods/HostName/profiles/IS_default/configuration/customer_wrapper.conf file

The host file in the Unix source server will have to be updated with an entry for the Proxy server IP - ST SaaS Host name:
- Ex: 123.123.123.123 dev-mq.oms.supply-chain.ibm.com
- The IP address above should be the Proxy Server/Firewall server in your network which connect to the actual IBM SaaS endpoint
- The HostName mentioned above should be the same that you use to configure the MQ Connection.
- Host file will usually be present inside the /etc/ location in UNIX server.

The below values need to be added up in extended settings for the SSL enabling of MQ connections and to handle the MQ read of data in RFH2 format.
- watt.WmMQAdapter.forceMQRFH2=true
  - This is required because when we try to read the data from the IBM SaaS MQ, as the data is published there in RFH2 format.
- watt.WmMQAdapter.SSL.Support=true
- watt.WmMQAdapter.Connection.CiphersList=AllCipherSpec

The setup issues for connection establishment are all documented under a support ticket in the SAG portal:
- SI-490344 Unable to connect to Cloud IBM SaaS MQ provider
We had several issues in using the Asynchronous message processing pattern for reading the messages from MQ.
When the data needs to be read from the IBM SaaS MQ’s we had an issue where we were unable to process it. Upon analysis it was found that IBM publishes the data MQRFH2 format. Hence we had to change our MQ notification to read that properly. Refer below:

Please note that the MQ connection host name should be the same in the connection and as well as in the UNIX host file entry (refer above).