CHLAUTH (Channel Authentication)

IBM MQ channel authentication—often shortened to CHLAUTH in operations runbooks—is the control plane that decides which remote systems may open channel connections to your queue manager and which user ID (MCAUSER) they run as once connected. The word appears twice in daily work: as a queue manager attribute you ALTER to ENABLED or DISABLED, and as the MQSC command prefix SET CHLAUTH that creates rules. Greenfield queue managers in modern releases ship with CHLAUTH enabled and default rules that block the worst anonymous cases, but every migration project eventually hits a partner who cannot connect until someone adds an ADDRESSMAP or SSLPEERMAP. Beginners who only learn TLS without CHLAUTH encrypt traffic while still allowing the wrong channel name from the wrong subnet to run as a powerful ID. This tutorial explains enabling CHLAUTH, CHLAUTHRULS, creating and displaying rules, rule types at a glance, events and logging, phased hardening, and how CHLAUTH fits with CONNAUTH and MCAUSER on channel definitions.

The Queue Manager Switch

ALTER QMGR CHLAUTH(ENABLED) tells the queue manager to evaluate channel authentication records on inbound bind attempts. CHLAUTH(DISABLED) stops evaluation—use only in controlled lab recovery, not as a permanent production workaround. DISPLAY QMGR CHLAUTH shows the current value alongside CHLAUTHRULS. Changing the switch does not delete rules; they remain in the repository for when you re-enable. Operations teams should treat DISABLED as a security exception requiring ticket approval and time limit.

1
2
3
4
ALTER QMGR CHLAUTH(ENABLED) CHLAUTHRULS(ENABLED)
DISPLAY QMGR CHLAUTH CHLAUTHRULS
* Lab only — do not leave production disabled:
* ALTER QMGR CHLAUTH(DISABLED)

CHLAUTHRULS and Default Rules

IBM supplies default channel authentication rules on many queue managers so that completely open anonymous remote access is not the factory behavior. CHLAUTHRULS(ENABLED) means those defaults participate in matching; CHLAUTHRULS(DISABLED) means only your explicit SET CHLAUTH rules apply—which can be stricter or accidentally looser depending on what you defined. Before disabling defaults, DISPLAY CHLAUTH(*) and export definitions. Security architects often keep defaults until explicit partner rules exist, then review whether defaults can be tightened. Never disable defaults and remove custom rules in the same change window without a rollback plan.

SET CHLAUTH Syntax Patterns

Rules are named. You SET CHLAUTH('rule-name') TYPE(...) with type-specific attributes, then ACTION(ALLOW), ACTION(BLOCK), or mapping attributes like MCAUSER and USERSRC(MAP). REPLACE on SET updates an existing rule. REMOVE CHLAUTH deletes a rule. Wildcard channel names such as '*' or 'SYSTEM.*' scope which channel definitions the rule applies to—incorrect scoping is a common bug: a rule intended for one SVRCONN accidentally applies to all channels.

1
2
3
4
5
6
7
SET CHLAUTH('ALLOW.PARTNER.IP') TYPE(ADDRESSMAP) +
  ADDRESS('198.51.100.22') CHLAUTH(ALLOW) DESCR('Hub SDR source')
SET CHLAUTH('MAP.PAYAPP.CERT') TYPE(SSLPEERMAP) +
  SSLPEER('CN=payapp,O=Corp,C=US') MCAUSER('apppay') +
  USERSRC(MAP) ACTION(ALLOW)
DISPLAY CHLAUTH('MAP.PAYAPP.CERT') ALL
REMOVE CHLAUTH('MAP.PAYAPP.CERT')

How Rules Match Connections

When a channel instance starts or binds, the queue manager gathers facts: source IP, TLS peer certificate subject if SSL is active, remote queue manager name from protocol, channel name, and user ID presented for client connections. Rules of each TYPE are evaluated according to IBM-defined precedence for your release—consult the product documentation rather than guessing order. The first applicable outcome may ALLOW, BLOCK, or MAP MCAUSER. BLOCK stops the connection and logs an event. MAP sets the effective MCAUSER for authorization to queues and objects. Misconfigured SSLPEER strings that do not match the real cert DN produce blocks that look like TLS failures in casual triage.

CHLAUTH Events and Operations

Security teams enable CHLAUTH event messages to feed SIEM or MQ event monitors. Operators should bookmark log message numbers for block events on their release. Runbooks need: partner name, channel name, source IP, cert DN, rule name from log, DISPLAY CHLAUTH output, and whether a change ticket added the rule. Quarterly audits compare active partner inventory to DISPLAY CHLAUTH(*) export. When partners migrate to new IPs or renew certificates, update rules before cutover, not after outage.

Phased Enablement Without Outage

1. Export DISPLAY CHLAUTH(*) and DISPLAY QMGR CHLAUTH CHLAUTHRULS from production.
2. Build lab queue manager mirror; enable CHLAUTH; run partner test scripts.
3. Add explicit ALLOW or MAP for every legitimate partner path.
4. Run negative tests (wrong IP must block).
5. Enable in production in a window; monitor logs and channel DISCINT traffic.
6. Remove temporary broad ALLOW rules created during migration.

CHLAUTH With CONNAUTH and TLS

CONNAUTH validates passwords or binds LDAP before channel bind completes. TLS encrypts and may present client certificates. CHLAUTH authorizes the channel path and maps identity. All three layers stack: a user can pass CONNAUTH and TLS yet still be blocked by CHLAUTH if IP is wrong, or pass CHLAUTH but fail 2035 on MQOPEN if MCAUSER lacks queue authority. Teach support staff the difference so they do not only chase SSLCIPH when the log clearly names a CHLAUTH rule.

Explainer: Building Security Layers

Think of CHLAUTH as the reception desk that checks your meeting room booking after security scanned your badge at the building entrance. CONNAUTH is the building badge; TLS is the sealed envelope you carry; CHLAUTH is whether you are allowed into the specific meeting room (channel) and which name tag (MCAUSER) you wear inside.

Explain Like I'm Five: CHLAUTH

CHLAUTH is the rule book that says who may use each MQ door and whether they get a special name tag when they come in.

Practice Exercises

Exercise 1

Write MQSC to enable CHLAUTH and DISPLAY all rules—what would you archive before a change?

Exercise 2

A partner moves IP—list every CHLAUTH record type you might need to update.

Exercise 3

Explain to a developer why TLS success does not guarantee MQPUT success.

Frequently Asked Questions

Test Your Knowledge