Interaction of CHLAUTH and CONNAUTH

How channel authentication records (CHLAUTH) and connection authentication (CONNAUTH) interact in IBM MQ, in the case of a single conversation on a channel.

Different types of bindings

IBM MQ supports two methods for an application to connect:

Local bindings: Applies when the application and queue manager are on the same operating image. CHLAUTH is not relevant to this type of application connection.
Client bindings: Applies when the application and queue manager use the network to communicate. The application and queue manager can be running on the same machine, or they can be on different machines. In IBM MQ, a client connection is handled in the form of a server-connection (SVRCONN) channel and, in this situation, both CONNAUTH and CHLAUTH are applicable.

Binding steps of the receiving end of a channel

When an application connects to a queue manager, a substantial amount of checking is performed to ensure that both ends of the channel understand what is supported by the other end. The receiving end of the channel does some extra checking, involving CHLAUTH and CONNAUTH, to ensure that the client is allowed to connect, and this process might also include a security exit as this can affect the result. This channel connecting phase is also referred to as the binding phase.

The following diagram lists the steps that a SVRCONN channel goes through when the server end (at the queue manager) starts:

Step 1: Receive a connection request

The channel initiator or listener receives a connection request from somewhere on the network.

Step 2: Is the address allowed to connect?

Before any data is read, IBM MQ checks the IP address of the partner against the CHLAUTH rules, to see if the address is in the BLOCKADDR rule. If the address is not found, and so not blocked, the flow proceeds to the next step.

Step 3: Read data from the channel

IBM MQ now reads the data into a buffer, and starts to process the sent information.

Step 4: Look up the channel definition

In the first data flow, IBM MQ sends, amongst other things, the name of the channel which the sending end is trying to start. The receiving queue manager can then look up the channel definition, which has all the settings that are specified for the channel.

Step 5: Call security exit (if defined)

If the channel has a security exit (SCYEXIT) defined, this is called with the exit reason (MQCXP.ExitReason) set to MQXR_INIT_SEC.

Step 6: Receive MQCSP

If necessary, construct one, as long as the user ID and password are supplied by the client.

If the client is a Java or JMS application running in compatibility mode, the client does not pass an MQCSP structure to the queue manager. Instead, if the application supplied a user ID and password, an MQCSP structure is constructed here.

Step 7: Adopt MQCSP user (if ChlauthEarlyAdopt is Y)

The user Id asserted by the client is authenticated.

If CONNAUTH is using LDAP to map an asserted distinguished name to a short user Id, the mapping happens in this step.

If authentication is successful, the user Id is adopted by the channel and is used by the CHLAUTH mapping step.Note: From IBM MQ Version 9.0.4 the ChlauthEarlyAdopt= Y parameter is automatically added to the channels stanza of the qm.ini file for new queue managers.

Step 8: CHLAUTH mapping

The CHLAUTH cache is inspected again to look for the mapping rules SSLPEERMAP, USERMAP, QMGRMAP, and ADDRESSMAP.

The rule that matches the incoming channel most specifically is used. If the rule has USERSRC(CHANNEL) or (MAP), the channel continues on binding.

If the CHLAUTH rules evaluate to a rule with USERSRC(NOACCESS), the application is blocked from connecting to the channel, unless the credentials are subsequently overridden with a valid user ID and password in Step 9.

Step 9: Call security exit (if defined)

If the channel has a security exit (SCYEXIT) defined, this is called with the exit reason (MQCXP.ExitReason) set to MQXR_SEC_PARMS.

A pointer to MQCSP will be present in the SecurityParms field of the MQCXP structure.

The MQCSP structure has pointers to the user ID (MQCSP.CSPUserIdPtr) and password (MQCSP.CSPPasswordPtr).

It is possible to change the user ID and password in the exit. The following example shows how a security exit would print the user ID and password values to an audit log:

if (pMQCXP -> ExitReason == MQXR_SEC_PARMS)
{
  /* It is not a good idea for security reasons to print out the user ID */
  /* and password but the following is shown for demonstration reasons */
  printf("User ID: %.*s Password: %.*s\n",
         pMQCXP -> SecurityParms -> CSPUserIdLength,
         pMQCXP -> SecurityParms -> CSPUserIdPtr,
         pMQCXP -> SecurityParms -> CSPPasswordLength,
         pMQCXP -> SecurityParms -> CSPPasswordPtr);

The exit can tell IBM MQ to close the channel, by returning MQXCC_CLOSE_CHANNEL in the MQCXP.Exitresponse field. Otherwise, channel processing continues to the connection authentication phase.

Note: If the asserted user is changed by the security exit, CHLAUTH mapping rules will not be re-applied to the new user.

Step 10: Authenticate the user

The authentication phase happens if CONNAUTH is enabled on the queue manager.

To check this, issue the MQSC command 'DISPLAY QMGR CONNAUTH'.

The following example shows the output of the command DISPLAY QMGR CONNAUTH from a queue manager running on IBM MQ for z/OS .

 CSQM201I !MQ25 CSQMDRTC DISPLAY QMGR DETAILS
 QMNAME(MQ25)
 CONNAUTH(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)
  END QMGR DETAILS
 CSQ9022I !MQ25 CSQMDRTC ' DISPLAY QMGR' NORMAL COMPLETION

The following example shows the output of the command 'DISPLAY QMGR CONNAUTH' from a queue manager running on IBM MQ for Multiplatforms.

     1 : DISPLAY QMGR CONNAUTH
AMQ8408: Display Queue Manager details.
   QMNAME(DEMO)
   CONNAUTH(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)

The CONNAUTH value is the name of an AUTHINFO IBM MQ object.

As operating system authentication (AUTHTYPE(IDPWOS)) is valid on both IBM MQ for Multiplatforms and IBM MQ for z/OS, the examples use operating system authentication.

The following example shows the shipped default object for AUTHTYPE(IDPWOS) from a queue manager running on IBM MQ for z/OS.

 CSQM293I !MQ25 CSQMDRTC 1 AUTHINFO FOUND MATCHING REQUEST CRITERIA
 CSQM201I !MQ25 CSQMDRTC DISPLAY AUTHINFO DETAILS
 AUTHINFO(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)
 AUTHTYPE(IDPWOS)
 QSGDISP(QMGR)
 ADOPTCTX(NO)
 CHCKCLNT(NONE)
 CHCKLOCL(OPTIONAL)
 FAILDLAY(1)
 DESCR()
 ALTDATE(2018-06-04)
 ALTTIME(10.43.04)
   END AUTHINFO DETAILS
 CSQ9022I !MQ25 CSQMDRTC ' DISPLAY AUTHINFO' NORMAL COMPLETION

The following example shows the shipped default object for AUTHTYPE(IDPWOS) from a queue manager running on IBM MQ for Multiplatforms.

 1 : display authinfo(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)
AMQ8566: Display authentication information details.
   AUTHINFO(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)
   AUTHTYPE(IDPWOS)                     ADOPTCTX(NO)
   DESCR( )                             CHCKCLNT(REQDADM)
   CHCKLOCL(OPTIONAL)                   FAILDLAY(1)
   ALTDATE(2015-06-08)                  ALTTIME(16.35.16)

The AUTHINFO TYPE(IDPWOS) has an attribute called CHCKCLNT. If the value is changed to REQUIRED all client applications have to supply a valid user ID and password.

If the user was authenticated in Step 7, the user will not be authenticated again unless the user or password in the SecurityParms field of the MQCXP structure was changed by a security exit in Step 9.

Step 11: Adopt the context of the user (if ADOPTCTX is YES)

We can set the ADOPTCTX attribute, which controls whether the channel runs under MCAUSER, or the user ID the application has supplied.

If the user ID asserted in the MQCSP, or SecurityParms field of the MQXCP structure, has been successfully authenticated and ADOPTCTX is YES, then the context of the user resulting from steps 7 and 8 is adopted as the context to use for this application, unless the user or password in the SecurityParms field of the MQCXP structure was changed by a security exit in step 9.

This asserted user ID is the User ID that is checked for authorization to use IBM MQ resources.

For example, we do not have an MCAUSER set on the SVRCONN channel, and your client is running under 'johndoe' on the Linux machine. Your application specifies user 'fred' in the MQCSP, so the channel starts running with 'johndoe' as the active MCAUSER. After the CONNAUTH check, the user 'fred' is adopted, and the channel runs with 'fred' as the active MCAUSER.

Step 12: Check the user is not blocked (BLOCKUSER)

If the CONNAUTH checking is successful, the CHLAUTH cache is then inspected again to check if the active MCAUSER is blocked by a BLOCKUSER rule. If the user is blocked, the channel ends.

Step 13: Check object authorisation

A check is made to ensure that the active MCAUSER has the appropriate authority to connect to the queue manager.

See Object Authority Manager, for more information.

See Object authority manager on IBM i, for more information.

Step 14: The connection completes: If the preceding steps complete successfully, the connection completes.

Parent topic: Channel authentication records

Related concepts

CONNAUTH

Interaction of CHLAUTH and CONNAUTH

Different types of bindings

Binding steps of the receiving end of a channel

Related concepts

Related information