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: Diagram representing the steps that a SVRCONN channel goes through when the server end (at the queue manager) starts.

Diagram representing 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 and ADOPTCTX=YES)

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 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 MQCSP user (If ChlauthEarlyAdopt=N and ADOPTCTX=YES)

You 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, you do not have an MCAUSER set on the SVRCONN channel, and your client is running under 'johndoe' on your 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.

Step13: Validate CHLAUTH CHCKCLNT requirements

If the CHLAUTH rule that was selected in step 8 additionally specifies a CHCKCLNT value of REQUIRED or REQDADM then validation is done to ensure that a valid CONNAUTH userid was provided to meet the requirement.

If CHCKCLNT(REQUIRED) is set a user must have been authenticated in step 7 or 10. Otherwise the connection is rejected.
If CHCKCLNT(REQDADM) is set a user must have been authenticated in step 7 or 10 if this connection is determined to be privileged. Otherwise the connection is rejected.
If CHCKCLNT(ASQMGR) is set then this step is skipped.

Notes:

If CHCKCLNT(REQUIRED) or CHCKCLNT(REQDADM) is set, but CONNAUTH is not enabled on the queue manager, the connection fails with a MQRC_SECURITY_ERROR (2063) return code due to the conflict in configuration.
The user is not re-authenticated in this step.

Step 14: Validate CONNAUTH CHCKCLNT requirements.

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

The CONNAUTH CHCKCLNT value is checked to determine what requirements are set for incoming connections:

If CHCKCLNT(NONE) is set then this step is skipped
If CHCKCLNT(OPTIONAL) is set then this step is skipped.
If CHCKCLNT(REQUIRED) is set then a user must have been authenticated in step 7 or 10. Otherwise the connection is rejected.
If CHCKCLNT(REQDADM) is set a user must have been authenticated in step 7 or 10 if this connection is determined to be privileged. Otherwise the connection is rejected.

Note: The user is not re-authenticated in this step.

Step 15: 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 16: The connection completes: If the preceding steps complete successfully, the connection completes.