User Authentication

Every message that lands on a production queue passed through at least two gates: something proved who the sender was, and something decided that identity was allowed to touch that object. IBM MQ separates those ideas into authentication and authorization, but beginners see only reason code 2035 and assume “bad password.” In reality the TCP connection and TLS handshake may have succeeded while CHLAUTH blocked the bind, or the bind succeeded while OAM denied a put because MCAUSER lacked rights. Client authentication covers MQI applications using SVRCONN, language clients asserting user IDs, password repositories, LDAP directories, and certificate-based logins mapped to service accounts. This tutorial walks through each mechanism, how AUTHINFO objects fit in, why MCAUSER is not optional in design reviews, z/OS RACF differences at a high level, REST user registries, and a practical troubleshooting order you can apply on first connect failure.

Authentication Versus Authorization

Authentication answers “Are you who you claim to be?” Authorization answers “May you perform this operation on this queue?” MQ can authenticate via password to an IDPWOS repository, OS userid validation, LDAP bind, or mutual TLS certificate subject. After the client is accepted on SVRCONN, puts and gets are checked against profiles: on distributed Linux, the Object Authority Manager (OAM) uses +connect, +put, +get, +inq, +dsp, and +set; on z/OS, RACF profiles in the MQ component govern the same ideas with different commands. A penetration test failure on +put is authorization even when the password was correct.

SVRCONN and the Client Login Flow

Applications do not open message channels (SDR/RCVR) for normal client work—they connect to a server-connection channel (SVRCONN). The client supplies connection details: queue manager name, channel name, host, port, and optionally user ID and password in MQCNO or JMS connection factory properties. The listener accepts TCP, TLS may run, then CHLAUTH rules evaluate the source IP, certificate DN, and asserted user. If allowed, the channel instance runs under an MCAUSER value either from the channel definition or from a CHLAUTH MAP rule. MQOPEN and MQPUT then use that identity for OAM checks. Changing only the password in LDAP without updating CHLAUTH USERMAP can still fail if the mapped MCAUSER was wrong all along.

1
2
3
4
5
6
7
8
9
DEFINE CHANNEL('APP.SVRCONN') CHLTYPE(SVRCONN) TRPTYPE(TCP)
ALTER CHANNEL('APP.SVRCONN') CHLTYPE(SVRCONN) MCAUSER('appmq')
SET CHLAUTH(DISABLED)  * never leave this in production — example only
SET CHLAUTH(ENABLED)
DEFINE CHLAUTH('APP.SVRCONN') TYPE(USERMAP) CHLTYPE(SVRCONN) +
  ADDRESS('*') USERSRC(CHANNEL) MCAUSER('appmq') ACTION(ALLOW)
SET AUTHREC OBJTYPE(QUEUE) PRINCIPAL('appmq') ENTITY('PAYMENTS.IN') +
  AUTHADD(GET,PUT,INQ,DSP)
* Client must connect with user allowed by USERMAP or cert map

AUTHINFO and Password Repositories

AUTHINFO objects tell the queue manager how to validate passwords. TYPE(IDPWOS) uses a file-based OS repository maintained with MQ commands (setmqaut-related tooling varies by platform—follow IBM docs for your release). TYPE(IDPWLDAP) points at LDAP servers for bind authentication. Misconfigured AUTHINFO produces generic connection failures in client logs while AMQERR01 mentions authentication service errors. Lab environments sometimes enable IDPWOS with a handful of test users; production should integrate LDAP or certificates to avoid duplicate password stores.

CHLAUTH USERMAP and BLOCKUSER

CHLAUTH TYPE(USERMAP) maps an asserted client user ID to an MCAUSER the queue manager trusts for OAM. This lets humans log in as jdoe while messages run under service ID appmq with narrow queue rights. TYPE(BLOCKUSER) denies known bad IDs such as default mqm or root from remote client connection—IBM ships default rules because remote admin over SVRCONN was a historic vulnerability. DISPLAY CHLAUTH(*) shows active rules; use SET CHLAUTH to enable after defining allows. Never disable CHLAUTH permanently to “fix” login—fix the map and grants instead.

Certificate-Based Client Identity

When TLS client authentication is required, the user ID may come entirely from the certificate distinguished name via SSLPEERMAP rather than a password. The pattern matches B2B partners who rotate certs through PKI instead of sharing passwords. SSLPEER patterns must match the cert DN string precisely enough—wildcards help but test after every renewal. See the mutual TLS and certificate validation tutorials for handshake details; this page focuses on the identity outcome for OAM.

z/OS Considerations

On z/OS, the channel initiator and security product (RACF) participate in establishing the control block execution identity. MCAUSER still names the intended ID, but profiles live in RACF classes for MQ resources. Teams operating hybrid estates should document which side authenticates LDAP users and which mainframe ID ultimately owns the put authority on shared queues reached via QSG or channels.

REST and Console Users

mqweb maintains its own user registry or LDAP realm for HTTPS. A user who can open the console is not automatically granted put access to all queues—configure queue manager authority for the Liberty-authenticated principal or map to a group your OAM understands. CSRF tokens and basic auth over TLS are standard in examples; production should use corporate SSO or certificate realms where available.

Explainer: Two Locks on the Door

Authentication is showing your badge at the building entrance. Authorization is the room key for the specific office. You can have a valid badge (password or cert) but still be unable to open the payments room (+put denied). Fix the right lock—sometimes the badge works but you need a different key holder name (MCAUSER).

Troubleshooting Checklist

1. Can you telnet or openssl s_client to the listener port?
2. Does CHLAUTH block in AMQERR01 during bind?
3. Is MCAUSER set and granted on the target queue?
4. For passwords, is AUTHINFO correct and user in repository/LDAP?
5. For 2035 after connect, run setmqaut or DISPLAY AUTHREC for the principal.

Explain Like I'm Five: User Authentication

Before you put a note in the class mailbox, the teacher checks your name tag (authentication) and checks whether you are allowed to use that mailbox today (authorization).

Practice Exercises

Exercise 1

Design USERMAP for developers jdoe and asmith both mapped to DEV-only MCAUSER with no production queue access.

Exercise 2

List log lines you expect when CHLAUTH BLOCKUSER stops user mqm from a remote IP.

Exercise 3

Password works in LDAP but 2035 on PUT—write the DISPLAY and setmqaut commands you run next.

Frequently Asked Questions

Test Your Knowledge