Channel Authentication Records

Before IBM MQ channel authentication (CHLAUTH), many queue managers accepted any remote program that knew a channel name and port, often running traffic as a powerful MCAUSER like mqm. Channel authentication records fix that by storing rules the queue manager evaluates every time a channel tries to bind—message channels from partners, SVRCONN from application servers, cluster senders from foreign queue managers. A record can allow the connection, block it with a clear event, or map the connection to a specific MCAUSER based on IP address, TLS certificate subject, remote queue manager name, or claimed user ID. Beginners see mysterious channel failures right after security hardening projects because administrators enabled CHLAUTH without adding maps for legitimate partners. This tutorial explains each CHLAUTH type, default rules on new queue managers, SET CHLAUTH and ALTER QMGR CHLAUTH settings, how records interact with TLS and CONNAUTH, operational DISPLAY patterns, and a phased approach to deny-by-default without outage.

Why Channel Authentication Exists

Channel names are not secrets—they appear in MQSC, CCDT files, and documentation. Firewall rules alone cannot prove which queue manager or application connected. CHLAUTH closes the gap by binding policy to observable connection facts: source IP, certificate DN, partner QMGR name from protocol, or MQI user ID. When a rule matches, actions include ALLOW, BLOCK, or MAP (set MCAUSER). Events can feed SIEM systems. Regulators expect CHLAUTH enabled on internet-facing listeners and on production hub queue managers even when traffic is internal-only, because lateral movement inside a data center is common.

Queue Manager CHLAUTH Settings

ALTER QMGR CHLAUTH(ENABLED) turns rule evaluation on. CHLAUTHRULS(DISABLED) versus ENABLED controls whether IBM default rules apply—beginners should read IBM documentation for their release before disabling defaults, because removing the last allow rule can lock out all remote channels. CHLAUTH(RECORDS) events help auditing. Plan maintenance windows when switching from DISABLED to ENABLED; have console access to revert or add emergency ADDRESSMAP rules for operations center IPs.

1
2
3
4
5
6
7
8
9
ALTER QMGR CHLAUTH(ENABLED) CHLAUTHRULS(ENABLED)
DISPLAY QMGR CHLAUTH CHLAUTHRULS
SET CHLAUTH('*') TYPE(ADDRESSMAP) ADDRESS('203.0.113.10') +
  CHLAUTH(ALLOW) DESCR('Partner hub sender')
SET CHLAUTH('PAYMENTS.APP') TYPE(SSLPEERMAP) SSLPEER('CN=payapp,O=Corp') +
  MCAUSER('apppay') USERSRC(MAP) ACTION(ALLOW)
SET CHLAUTH('*') TYPE(BLOCKUSER) USERLIST('nobody','guest') +
  DESCR('Deny well-known weak IDs')
DISPLAY CHLAUTH(*) ALL

ADDRESSMAP in Practice

ADDRESSMAP is the first tool many teams use for fixed partner IPs: the data center sending SDR traffic always comes from 203.0.113.10, so ALLOW that address on RCVR channels or MAP to a dedicated MCAUSER with put authority only on intended queues. Wildcards and ranges follow IBM syntax—verify with DISPLAY after SET. Cloud and Kubernetes partners with changing IPs push teams toward SSLPEERMAP instead of ADDRESSMAP alone. NAT can make many internal hosts appear as one address—design maps carefully so you do not over-allow.

SSLPEERMAP and TLS

When SSLCAUTH requires client certificates, SSLPEERMAP matches the certificate distinguished name (DN) or pattern to MCAUSER. Example: CN=payapp,O=Corp maps to apppay for channel PAYMENTS.APP. Patterns can use wildcards per IBM rules. Certificate renewal requires updating SSLPEER rules before old certs expire—runbooks should link PKI ticket to CHLAUTH DISPLAY. Mismatch between cert DN and SSLPEER string is a top cause of BINDING failure after TLS succeeds.

QMGRMAP and Cluster Traffic

QMGRMAP authorizes connections asserting a remote queue manager name—common for cluster channels and trusted SDR partners. A rule might allow QMGRNAME(QM_PARIS) to connect to CLUSRCVR channels. Spoofing concerns mean QMGRMAP is usually combined with TLS mutual authentication or private network paths. Document which remote QMGR names are legitimate in cluster repositories versus point-to-point links.

USERMAP and BLOCKUSER

USERMAP inspects user IDs presented during client connect—useful when applications log in with distinct IDs but share one SVRCONN name. MAP or BLOCK per user list. BLOCKUSER denies specific IDs globally—block guest, anonymous, or deprecated service accounts. Neither replaces LDAP CONNAUTH; they apply after or alongside identity establishment depending on configuration.

Default Rules and Hardening Phases

1. Inventory all inbound channels (RCVR, SVRCONN, CLUSRCVR) and partner CONNAME sources.
2. DISPLAY CHLAUTH(*) and document existing defaults.
3. Add explicit ALLOW or MAP rules for each partner before removing broad defaults.
4. Enable CHLAUTH in lab; run integration tests including negative tests (wrong IP should block).
5. Enable in production with monitoring on CHLAUTH block events.
6. Review quarterly when partners add IPs or renew certificates.

Relationship to MCAUSER on Channel Definition

MCAUSER on DEFINE CHANNEL sets the default identity when no rule maps differently. CHLAUTH MAP overrides that default for matching connections. If channel MCAUSER is mqm and no SSLPEERMAP exists, TLS might encrypt traffic but the connection still runs as a powerful ID—avoid. Principle of least privilege: channel MCAUSER to a low-privilege ID, SSLPEERMAP to application-specific IDs where certs allow.

Explainer: Bouncer With a Guest List

CONNAUTH checks your ID card is real. Channel authentication records are the bouncer list that says which door (channel) you may enter and which employee badge (MCAUSER) you wear inside. No list means anyone who guesses the door name might walk in wearing an admin badge.

Troubleshooting Blocks and BINDING Failures

• Search queue manager log for AMQ9777 and related CHLAUTH messages naming the rule that fired.
• DISPLAY CHLAUTH matching rule name; verify ADDRESS, SSLPEER, or QMGRNAME fields.
• Compare partner certificate DN character-for-character with SSLPEERMAP pattern.
• Temporarily add narrowly scoped ALLOW for ops IP only—not wildcard ALLOW * in production.
• Confirm CHLAUTH(ENABLED) on both queue managers in a pair if testing asymmetric configs.

Explain Like I'm Five: Channel Authentication Records

They are a list of rules that say which computers and which ID cards may use each MQ door, and whether to give them a special name tag when they come in.

Practice Exercises

Exercise 1

Write SET CHLAUTH for SSLPEERMAP and ADDRESSMAP for one SVRCONN used by a known app server subnet.

Exercise 2

List three symptoms operators see when CHLAUTH blocks a partner SDR.

Exercise 3

Draft a change request template: partner name, IP, cert DN, channel names, MCAUSER, rollback SET CHLAUTH.

Frequently Asked Questions

Test Your Knowledge