3. IBM MQ setup commands for mTLS configuration
In this section, we’ll configure IBM MQ to use TLS certificates for secure communication between the server and client, enabling mutual TLS (mTLS).
- Step 1: Create and Start the Queue Manager
IBM MQ uses a queue manager to manage queues and channels, acting as the central component for message handling.
crtmqm JITENDRA_QM # Create the queue manager
strmqm JITENDRA_QM # Start the queue manager
- Step 2: Configure the Queue Manager
The runmqsc command allows you to issue MQSC commands to configure and manage the queue manager.
runmqsc JITENDRA_QM
- Step 3: Define TLS Key Repository and Certificate Label
TLS in IBM MQ requires a key repository containing personal and CA certificates for secure communication.
ALTER QMGR SSLKEYR('C:\generated-output\mq-kdb\qm')
ALTER QMGR CERTLABL('CN=mqserver,OU=ISL,O=IBM,L=Bangalore,ST=KA,C=IN')
- Step 4: Define SVRCONN Channel with TLS Settings
Channels are communication paths in MQ; SVRCONN channels are used by client applications to connect to the queue manager.
DEFINE CHANNEL('ACE.SVRCONN') CHLTYPE(SVRCONN) SSLCAUTH(REQUIRED)
SSLCIPH('ANY_TLS13_OR_HIGHER') MCAUSER('MUSR_MQADMIN')
CERTLABL('CN=mqserver,OU=ISL,O=IBM,L=Bangalore,ST=KA,C=IN')
SSLPEER('CN=aceclient,OU=ISL,O=IBM,L=Bangalore,ST=KA,C=IN')
- Step 5: Configure Channel Authentication Rules
CHLAUTH rules in IBM MQ control which users or certificates are allowed to connect through specific channels.
- Step 6: Refresh Security Settings
After modifying authentication settings, you must refresh security to apply the changes.
ALTER QMGR CONNAUTH(' ')
REFRESH SECURITY
- Step 7: Create a Demo Queue
Queues are used to store messages; a local queue is managed by the queue manager and used for testing or production.
DEFINE QLOCAL('JITENDRA.QUEUE')
- Step 8: Display and Verify Configuration
Use display commands to verify the current configuration of channels, queue manager, and authentication rules.
DISPLAY CHLAUTH('ACE.SVRCONN')
DISPLAY CHANNEL('ACE.SVRCONN')
DISPLAY QMGR
- Step 9: Stop the Queue Manager (if needed)
Stopping the queue manager gracefully ensures all resources are released and transactions are completed.
endmqm -i JITENDRA_QM
Display Queue Manager details
DIS CHL(ACE.SVRCONN)
DISPLAY CHLAUTH(ACE.SVRCONN)
Note: Platform Note: Windows vs. UNIX/Linux
The IBM MQ setup and commands provided in this blog were tested on Windows. If you're running IBM MQ on UNIX/Linux, please be aware of the following differences:
- User Permissions:
On Windows, the default administrative user for MQ is typically MUSR_MQADMIN.
On UNIX/Linux, this is usually mqm. You should replace MUSR_MQADMIN with mqm (or another appropriate user) in channel and CHLAUTH configurations.
- File Paths:
Windows uses backslashes (\) in file paths, while UNIX/Linux uses forward slashes (/). Update paths accordingly when configuring SSLKEYR or referencing certificate files.
- Command Syntax:
Most MQSC commands remain the same, but shell commands (e.g., file operations, scripting) may differ between platforms.
Note: At the end of this step my MQ on-premise is ready with mTLS.
Key things to verify at IBM MQ Side:
SSLKEYR('C:\generated-output\mq-kdb\qm')
SSLPEER('CN=aceclient,OU=ISL,O=IBM,L=Bangalore,ST=KA,C=IN')
CERTLABL('CN=mqserver,OU=ISL,O=IBM,L=Bangalore,ST=KA,C=IN')
SSLPEER('CN=aceclient,OU=ISL,O=IBM,L=Bangalore,ST=KA,C=IN')
SSLCAUTH(REQUIRED)
SSLCIPH(ANY_TLS13_OR_HIGHER)
Note: Cipher Suite Note: TLS 1.3 vs. TLS 1.2
In this blog, I’ve used SSLCIPH('ANY_TLS13_OR_HIGHER') to configure the SVRCONN channel for TLS communication.
While TLS 1.3 offers improved security and performance, TLS 1.2 is still widely considered secure and compatible with many enterprise environments.
If you're working in an environment where TLS 1.3 is not supported or you need broader compatibility, you can use:
SSLCIPH('ANY_TLS12_OR_HIGHER')
4. Develop integration BAR file and policy using ACE Toolkit to publish to IBM MQ using ACE MQOutput Node.
Http Input==> Compute ==> MQOutput ==> Http Reply
- Step 1: Create an integration BAR to publish to IBM MQ
As part of this step, we create an integration BAR file using the ACE Toolkit, which includes the following nodes: HTTP Input → Compute → MQOutput → HTTP Reply. This flow allows us to publish messages to an IBM MQ queue, and for verification purposes, the same message is also returned in the HTTP Reply node, enabling us to observe the output directly.
- Step 2: Create an MQ policy which is used by the integration shown above.
Note: By the end of this step we have an integration BAR file and policy ready using the ACE Toolkit, which will be deployed in IWHI.
5. Configuration Required on IBM webMethods Hybrid iPaaS (IWHI) Side
- Step 1: PNA (Private Network Access), switch client configuration
Uses PNA (Private Network Access) configuration, it includes switchclient.json (named as mq-agent.json in my case) for routing through the Switch Server.
-
Step 2: Create a generic file configuration with ACE client KDN and sth (mq-via-switch-kdb-generic)
A configuration using generic files, containing the ACE client KDBS, and the path is /home/aceuser/generic/ace-kdb, provided in the server config.
-
Step 3: Create a server config configuration (mq-server-config)
Create a server config configuration and populate it with the mqKeyRepository location, for ACE to be able to locate the KDB.
Note: we will find this from the previous step for generic file configuration.
- Step 4: Create a configuration for the policy exported from the ACE Toolkit in IWHI (mq-integration-policy)
- Step 5: Attach all the ACE configurations to your ACE Runtime
6: Configuration required on On-Prem Secure Agent side
- Go to IWHI PNA (Private Network Access) in IWHI.
- For mq-agent(IWHI Secure Agent configuration), click on view setup instructions and follow the steps. For more information see Private Network Agent.
- Content of switchclient.json values as below.
switchclient.json
{
"id": "8b45e2dd-cc8f-44b1-a7d7-4089b87442ef",
"admin": "enabled",
"logLevel": "debug",
"callableFlows": "enabled",
"endpoints": [
{
"name": "localhost",
"hostname": "localhost",
"port": 1414,
"useTLS": false,
"certs": {
"key": "",
"cert": "",
"ca": [
""
],
"rejectUnauthorized": false
}
}
],
"switch": {
"url": "wss://default-switch-server-switch-acdev2529567.switch.a-vir-d1.appconnect.ipaas.ibmappdomain.cloud:443",
"certs": {
"ca": [
"*******"
],
"cert": "*******",
"key": "*******",
"rejectUnauthorized": true
}
},
"displayName": "mq-test-on-premise"
}
Note: It is important to clarify, although the switchclient.json file shows "useTLS": false under the endpoints section, the overall MQ client connection is still fully secure.
Here’s how it works, the connection between IBM App Connect Enterprise (ACE) and the on-premises MQ is protected by end-to-end TLS encryption.
Even though the Switch Client itself doesn’t initiate a TLS handshake with the MQ endpoint (hence "useTLS": false), the MQ client is already configured to use TLS. This means the MQ traffic is encrypted before it enters the secure tunnel created by the Switch Server.
So in effect, the data is fully encrypted, first by MQ’s own TLS layer, and then again by the secure WebSocket (WSS) tunnel. At no point is the data sent in plaintext. This setup ensures a strong security posture and protects the data throughout its entire journey, both inside and outside the cloud container.
-
Start switch agent (start with debug to view the details only), in realtime configuration debug
(-d ) should be disabled.
secureagent.exe -c C:\secureagent-win\switchclient.json -l C:\secureagent-win\log -d
7. Verify integration using CURL, and confirm the is published to MQ with TLS on-premise also the HttpReply.
curl -X POST https://jitendra-mq-tls-https-acdev2529567.a-vir-d1.appconnect.ipaas.ibmappdomain.cloud/putToMQ \
-H "Content-Type: application/json" \
-d '{"message": "Hello"}' \
--output -
HttpReply:
MD ????"MQSTR ????????{"message": "Hello"}
Data Published to IBM MQ:
IWHI Activity Log: Connected to MQ Successfully:
IWHI Flow:
Conclusion:
In today’s evolving hybrid cloud landscape, securely connecting cloud-native applications with on-premises systems is not just beneficial—it’s essential. This blog showcased how IBM webMethods Hybrid iPaaS (IWHI), together with IBM App Connect Enterprise (ACE), can be used to build a secure, scalable, and modular integration with an on-premises IBM MQ queue manager.
Using ACE Toolkit, we designed a message flow with nodes like HTTP Input → Compute → MQOutput → HTTP Reply, enabling seamless message publishing to MQ while maintaining visibility through HTTP responses. The integration is further enhanced by the use of a Switch Server and Switch Clients, which establish secure port forwarding between cloud and on-premise environments.
A key advantage of this setup is that the tunnel is initiated via outbound connections from the private network, meaning no inbound firewall ports need to be opened, significantly simplifying network configuration and improving security.
Importantly, the architecture ensures end-to-end TLS encryption, protecting data from the ACE runtime all the way to the MQ server. The MQ client encrypts traffic before it enters the secure tunnel, resulting the data is fully encrypted, first by MQ’s TLS layer and then by the secure WebSocket (WSS) tunnel. This guarantees that data is never transmitted in plaintext, maintaining a strong security posture throughout its journey.
Overall, this approach simplifies hybrid connectivity while meeting enterprise-grade security standards, making it a robust and future-ready solution for modern integration challenges.