Channel Authentication Failures

Channel authentication failures are IBM MQ refusing an inbound channel partner at the front door. With CHLAUTH ENABLED, every RCVR, CLUSRCVR, and SVRCONN bind is checked against rules you defined—or default rules IBM ships to block the worst anonymous cases. The failure is intentional security: a partner on the wrong IP, a certificate with the wrong distinguished name, or a remote queue manager name not on your allow list should not reach RUNNING and inherit a powerful MCAUSER. Beginners often confuse these failures with TLS handshake errors or with reason code 2035 on MQOPEN; this tutorial focuses on CHLAUTH-specific symptoms, reading block events, fixing ADDRESSMAP SSLPEERMAP QMGRMAP and BLOCKUSER issues without turning security off, and building a partner onboarding checklist so cutover night is not the first time you DISPLAY CHLAUTH.

When Authentication Runs

After TCP connect and usually after TLS completes, the queue manager evaluates channel authentication records during channel bind. Facts available include source IP address, TLS peer certificate subject if present, remote queue manager name from protocol, channel name, and for some client connections the user ID asserted by the client. Rules of types ADDRESSMAP, SSLPEERMAP, QMGRMAP, USERMAP, and BLOCKUSER combine per IBM precedence for your release—never guess order; read the documentation for your fix pack. OUTCOME BLOCK stops the connection and writes a log entry naming the rule. OUTCOME ALLOW or MAP permits progress; MAP may set MCAUSER before object authority checks run.

Reading the Error Log

Search for CHLAUTH, channel authentication, or the channel name in AMQERR at the timestamp of the failed connect. IBM messages often include the rule name that fired—copy that name into DISPLAY CHLAUTH('rule') ALL. Compare ADDRESS in the log to your rule patterns: a partner behind NAT may appear as a concentrator IP you did not whitelist. Compare certificate DN character-for-character to SSLPEER. Compare remote queue manager name to QMNAME in QMGRMAP. If the log is vague, enable channel authentication events temporarily in a test window and reproduce one failure with a known good partner to contrast log format.

Fixing ADDRESSMAP Blocks

1
2
3
4
5
6
DISPLAY CHLAUTH('BLOCK.ALL') ALL
DISPLAY CHLAUTH(*) WHERE(TYPE EQ ADDRESSMAP)
SET CHLAUTH('ALLOW.PARTNER.A') TYPE(ADDRESSMAP) +
  ADDRESS('203.0.113.10') CHNAME('PARTNER.IN') ACTION(ALLOW) +
  DESCR('Partner data center egress 2026')
DISPLAY CHLAUTH('ALLOW.PARTNER.A') ALL

Scope rules to CHNAME where possible so one partner ALLOW does not open every SVRCONN on the queue manager. For cloud partners with changing IPs, migrate toward SSLPEERMAP rather than endlessly widening ADDRESS ranges. Document each ALLOW with ticket number and review date. Remove rules when partners decommission.

Fixing SSLPEERMAP Blocks

TLS succeeded but CHLAUTH failed—classic SSLPEER mismatch. Export the live certificate DN from the partner, update SET CHLAUTH SSLPEER, and retest. If SSLCAUTH is OPTIONAL on RCVR, partners without client certs cannot match SSLPEERMAP; either require mutual TLS or use ADDRESSMAP and QMGRMAP for that path. After PKI renewal, runbooks must include CHLAUTH updates in the same change window as SSLKEYR—not the week after.

Fixing QMGRMAP and Cluster Blocks

New cluster member QM_NEW connects to CLUSRCVR but no QMGRMAP allows QM_NEW—the bind fails while older members work. Add TYPE(QMGRMAP) with QMNAME('QM_NEW') on every member that must accept inbound from QM_NEW, or use a maintained wildcard pattern if policy allows. Cluster cutovers fail silently on one link when only some members received the rule—automate CHLAUTH distribution in cluster change pipelines.

BLOCKUSER and SVRCONN

Applications connecting through SVRCONN sometimes assert user IDs like guest, admin, or legacy service accounts. BLOCKUSER rules exist to deny those IDs even when IP and cert look fine. Fix the application to use a proper identity or map via SSLPEERMAP and USERMAP rather than removing BLOCKUSER globally. Penetration tests probe weak asserted IDs—keep the deny list.

CHLAUTH Versus 2035

• CHLAUTH failure—channel never RUNNING; log says CHLAUTH or channel authentication.
• 2035 on MQOPEN—channel may be RUNNING; MCAUSER lacks +put on queue.
• Both—fix CHLAUTH first, then OAM grants for mapped MCAUSER.
• CONNAUTH—separate facility for some client authentication paths.

Safe Partner Onboarding Checklist

1. Confirm CHLAUTH ENABLED and CHLAUTHRULS policy documented.
2. Lab connect with partner IP and cert from production-like path.
3. Add ADDRESSMAP or SSLPEERMAP with CHNAME scope.
4. MAP MCAUSER to least-privilege ID; grant OAM on target queues only.
5. Production connect test; capture DISPLAY CHSTATUS RUNNING.
6. Schedule rule review in access management calendar.

Explainer: Bouncer With a Guest List

CHLAUTH is the bouncer checking the guest list at the door. Channel authentication failure means your name is not on the list—or you are on the blocked list—even if you arrived in a fancy car (TLS encryption).

Explain Like I'm Five: Channel Authentication Failures

The club has a list of who may enter. If your name is not on the list, the door stays closed even if you know the password to the secret handshake.

Practice Exercises

Exercise 1

Given a log line with CHLAUTH rule BLOCK.SVRCONN.ALL, write DISPLAY and SET commands to add a narrower ALLOW for one channel.

Exercise 2

Distinguish three failure scenarios: handshake, CHLAUTH, 2035—and assign first diagnostic command for each.

Exercise 3

Design SSLPEERMAP plus BLOCKUSER for a microservice SVRCONN without global DISABLE CHLAUTH.

Frequently Asked Questions

Test Your Knowledge