Principal permissions are how IBM MQ attaches OAM authority bits to identities—human users, application service accounts, and groups—not to individual TCP connections. The queue manager must decide which name to evaluate on every MQOPEN: the password you typed, the MCAUSER on the SVRCONN, the certificate mapped by CHLAUTH, or the OS account for bindings. That decision is as important as the grants themselves. A perfect setmqaut matrix on mqfinance is useless if the application actually runs as mqbatch. This tutorial explains principals versus permissions, user versus group grants, effective identity resolution order, MCAUSER and ADOPTCTX interaction, certificate mapping to principals, naming conventions across LDAP and Unix, onboarding and offboarding workflows, and auditing principals against directory groups.
The principal is who. The permission is what they may do. setmqaut -p order_svc +put on ORDERS.IN binds the put permission bit to the order_svc principal. dspmqaut shows that binding. Changing the principal name without updating grants is a common migration defect—rename the LDAP account and every queue manager needs setmqaut updates or group membership fixes.
| Principal source | Scenario | Grant to |
|---|---|---|
| MQCSP userid (ADOPTCTX YES) | Remote Java client with password | Same userid string |
| MCAUSER on SVRCONN | Shared channel, ADOPTCTX NO | MCAUSER value |
| CHLAUTH SSLPEERMAP | Certificate CN=app01 | Mapped userid |
| OS logon (bindings) | Local batch on QM host | OS username |
| LDAP group membership | Role-based access | Group principal -g |
User principals are single accounts such as mqorders or app_payments. Grant directly with setmqaut -p when only one application uses the ID. Match LDAP attribute to MQ string—sAMAccountName versus userPrincipalName breaks audits when dspmqaut uses a different spelling than CONNAUTH presented. Service accounts should be non-interactive, long password or certificate, and documented in CMDB with owning team.
123setmqaut -m QM1 -n PAYMENT.IN -t queue -p mqpay +put +connect setmqaut -m QM1 -n PAYMENT.OUT -t queue -p mqpay +get +browse +connect dspmqaut -m QM1 -n PAYMENT.IN -t queue -p mqpay
Group principals let you grant once to MQ.APP.PAYMENTS and add developers or servers to that group in Active Directory or Unix groups. OAM unions authorities from all groups the user belongs to plus user-specific grants. Prefer groups for roles: producers, consumers, operators-readonly. Revoke access by removing directory membership faster than hunting hundreds of setmqaut lines. dspmqaut -g shows group-level grants; confirm user is member with id or ldap tools.
Message channels set MCAUSER so remote puts execute under a known ID—mqbridge, not the remote operator personal login. Receiver MCAUSER must have put authority on target queues. SVRCONN MCAUSER acts as default when clients do not adopt context. Using mqm or admin IDs as MCAUSER in production centralizes risk—any channel compromise inherits admin rights. Map to dedicated service principals per application or domain.
CHLAUTH rules can map SSLPEER('CN=app01,O=Corp') to USERMAP NEWUSER('mqapp01'). OAM then checks mqapp01. setmqaut must target mqapp01, not the certificate DN string. Rotate certificates without renaming mapped principals when possible to avoid grant churn. Document mapping tables alongside firewall and DNS records.
Permissions are rules on the wall. The principal is the name on your factory badge. If you borrow someone else badge, the rules apply to their name, not yours—MCAUSER and mapping choose which badge OAM reads.
Principals are evaluated on the queue manager that owns the object. Cluster workloads may put on QM1 while the app connects to QM2—grants must exist where the object lives or cluster aliases route correctly. Standardize principal names across data centers so DR runbooks do not require renamed grants. Repository cache does not replace OAM on each member.
Your name tag tells the teacher which rules are for you. Group tags mean everyone in the red team shares the same rules. Principal permissions mean the rules are written for a name, not for a random stranger.
Trace effective principal for SVRCONN with MCAUSER(mqsvc), ADOPTCTX NO, and MQCSP user app01.
Design group-based grants for three apps sharing one queue manager.
Write offboarding checklist including directory and setmqaut steps.
1. A principal can be:
2. MCAUSER is set on:
3. ADOPTCTX YES uses:
4. Group grants use setmqaut: