Connection Authentication & Channel Authentication Record interactions

RobParker |Oct 25 2017 Updated

Introduction

Connection Authentication was added into IBM MQ in version 8, it allows users to configure their Queue Manager to challenge connecting client applications to provide credentials and then authenticate those credentials with a repository. Since being added, there have been several enhancements and additions added in the IBM MQ 8 fix packs, I have detailed these in the table below:

Before Connection Authentication was added, users who wanted to perform authentication had two choices:

1. Use TLS with mutual authentication enable.
2. Use a security exit (or an alternative OAM)

As well as choosing one of the options above, users had to ensure that applications that were authenticated could then be properly authorized. This could be performed by using several methods, but most notably by using Channel Authentication records to filter connections and map them to a specific user (which was then granted authorities).

With the addition of Connection Authentication providing authentication (and having some linkage to authorization) many people have asked “How does Connection Authentication link with Channel Authentication records?”

This blog post will not go into details about how to specifically configure all aspects of Connection Authentication, this has already been covered in blog posts and the knowledge centre. But instead aims to provide some guidance and considerations to users implementing Connection Authentication and hopefully answered the question above. This blog post will contain 3 parts:

1. How Connection Authentication & Channel Authentication records behave with authorization (MCAUSER & ADOPTCTX)
2. Details of an important MQ Explorer bug fix that was delivered in 8.0.0.3 and how it impacts Connection Authentication & Channel Authentication records.
3. Details of a bug fix that was delivered in 8.0.0.5 and how it impacts Connection Authentication & Channel Authentication records.

Connection Authentication and Channel Authentication Records

Channel Authentication records allow you to permit or block connections based on a variety of different parameters (Client User, IP Address/hostname, etc). When a connection is permitted, you have two options: either the connection can continue with no changes to the MCAUSER (the user ID presented by the application) or the MCAUSER can be manipulated to a specified value (based on the channel authentication records). The MCAUSER is what is used later for authorization checks and, providing the authorization checks were successful, is what is displayed in object status fields for active connections. This makes it vitally important to understand your security configuration and test to ensure that all clients connecting to your queue manager get assigned the correct MCAUSER.

Connection Authentication contains a feature that also allows you to manipulate the MCAUSER providing the connection authentication step was successful, this is configured using the ADOPTCTX attribute on the AUTHINFO objects. ADOPTCTX can be set to one of 2 values, either NO or YES (NO being the default). When ADOPTCTX(NO) is used, Connection Authentication will authenticate the user id supplied by the application in the MQCSP structure, but make no changes to the MCAUSER. When ADOPTCTX(YES) is set, once a user id has successfully passed authentication, the MCAUSER will be updated with that authenticated user id.

With both Channel Authentication and Connection Authentication altering the MCAUSER one must have a higher precedence than the other. Which User id is used in the MCAUSER depends on 2 factors: firstly, what ADOPTCTX is set to and finally whether a user id is provided by a client application in the MQCSP structure for authentication..

ADOPTCTX NO

When ADOPTCTX(NO) is configured the behavior is always the same, because Connection Authentication performs no alteration of the MCAUSER the Channel Authentication records will also be able to manipulate the MCAUSER regardless of whether credentials are supplied or not.

ADOPTCTX YES

In the case where ADOPTCTX(YES) is used the behaviour differs on whether a user id is supplied for authentication or not. When a user ID is supplied in the MQCSP structure, that is the user ID set into MCAUSER and Channel Authentication rules have no effect on the MCAUSER. If no user ID is supplied, Channel Authentication rules can affect the MCAUSER. However, when a user id is supplied, Connection Authentication will set the MCAUSER and this will take a higher precedence than the Channel Authentication record; i.e. will be the final MCAUSER used.

MCAUSER

Despite here we’ve only focused on Channel Authentication records and Connection Authentication up until this point, the MCAUSER that is used for authorization can be set to a user by one of 5 features in total (in ascending precedence):

1. Who the client application is running as
2. The value in the MCAUSER attribute in the channel definition
3. The value in the MCAUSER of a MAP channel authentication record
4. The user supplied in the MQCSP - ADOPTCTX(YES) only
5. A value supplied by a security exit

Although this blog post has only focussed on Channel Authentication records versus Connection Authentication, in the cases where Connection Authentication is used but Channel Authentication is not then if the MCAUSER has not been set by Connection Authentication it will be set by either the Channel Definition or Client Application.

I have included the table below as a summary for the MCAUSER depending on the ADOPTCTX setting and whether credentials are supplied:

Even though when ADOPTCTX(YES) is configured Channel Authentication rules will have no effect on the final value of the MCAUSER, they will not be disabled. As such if you have rules that block connections, these will still work. However, if you are blocking access by assigned the MCAUSER of a connection to a user ID that does not exist, this will not work as the ADOPTCTX(YES) will change the MCAUSER to a different user. For example, the two channel authentication rules below perform action when considered on their own:

1. CHLAUTH('*') TYPE(ADDRESSMAP) ADDRESS('*') USERSRC(NOACCESS)
2. CHLAUTH('*') TYPE(ADDRESSMAP) ADDRESS('*') USERSRC(MAP) MCAUSER('*NOBODY')

When ADOPTCTX(NO) is used, either of the rules above will block any connection that attempts to connect to the Queue Manager.

However, when ADOPTCTX(YES) is used, only the first rule will block any connection. The second rule will not always block as if a valid user ID is supplied to the Queue Manager in the MQCSP structure. This user ID will be adopted and used as the final MCAUSER value instead of the '*NOBODY' user.

When you are designing your security configuration it is important that you keep this in mind to ensure you don't allow users through when you believe you are blocking them.

Summary

In Summary, Connection Authentication has a higher precedence than Channel Authentication but only in the cases where ADOPTCTX is set to YES and credentials are supplied. What you want to set ADOPTCTX to depends entirely on how you plan to handle your security and access to your system:

If you want to use Authentication and allow users to supply their own credentials for logging in (which you provide authority for) then using ADOPTCTX(YES) and enforcing credentials being supplied using CHCKCLNT(REQUIRED) would be recommended.
If, however, you want users to authenticate with a set of IDs but you want more specific controls over how they appear in the MCAUSER field and their authorizations then using ADOPTCTX(NO) with Channel Authentication mapping rules may be the best choice for you.

Change in MQ Explorer in MQ v8.0.0.3 - Compatibility mode

Before Connection Authentication was released in MQ v8, Java Clients already had the ability to provide different user ids in connections. This was performed by placing the user provided inside the MQCD data structure (referred to as the asserted ID), however there is no way of checking the asserted ID credentials. When Connection Authentication was implemented we added the ability for Java Clients to provide credentials into the MQCSP structure. In order to allow compatibility between new v8 Java Clients and old Queue Manager configurations (which relied on the asserted user ID being set) and new Queue Manager configurations (which relied on the user ID being supplied in the MQCSP), we added a switch to Java Clients called "Compatibility mode". This switch when enabled would tell Java Clients to use the old method of supplying credentials and when disabled would tell the Java Clients to use the new method (supply both an asserted user ID set to the user ID the application is running as and a user credentials in the MQCSP). As MQ Explorer is a Java Client, Compatibility mode was added to it and could be easily enabled or disabled using a tick box on the "User Authentication" section of a remote Queue Manager set-up.

A bug was found with MQ Explorer that meant that if you tried to disable compatibility mode by unchecking the tick box, MQ Explorer would show it as disabled, but operated as if was enabled. This problem was fixed in MQ 8.0.0.3 and the details of the problem were released in security bulletin (CVE-2015-1967).

How it relates to Connection Authentication & Channel Authentication

What this means for Connection Authentication and Channel Authentication is the change of behavior in MQ v8.0.0.3 when you are using MQ Explorer to connect to a Queue Manager and have compatibility mode disabled.

If we assume the following scenario:

• MQ Explorer is running under UserA and will supply UserB for Authentication.
• MQ Explorer will connect via a channel over TCP.
• A USERMAP Channel Authentication record is defined for it that will Block UserB if it the connecting application is running as it (in the MQCD).
• ADOPTCTX is set to NO

In 8.0.0.0, 8.0.0.1 & 8.0.0.2, regardless of if you enabled or disabled Compatibility mode, the behavior will always be that connection will be blocked (as the user ID UserB will always be set in the MQCD and then picked up by the Channel Authentication record).

In 8.0.0.3 and above, when Compatibility mode is enabled the connection will be blocked as before, however when Compatibility mode is disabled the connection will not be blocked. This is because when MQ Explorer connects the MQCD contains UserA and the MQCSP contains UserB. UserB is used for Authentication and then discarded as ADOPTCTX is set to NO. When the Channel Authentication record checks the MQCD it finds UserA, which does not match it and so it does not block it.

Summary

In Summary, a fix delivered in MQ 8.0.0.3 causes a change in behavior for MQ explorer when Compatibility mode is disabled, this was a by-product of a fix for a bug and is only applicable MQ Explorer.

Channel Authentication early adopt change

In 8.0.0.5 a fix was delivered to correct a problem where when ADOTPCTX(YES) was configured, a connection could be blocked by a channel authentication rule before the supplied user ID was adopted and permitted by a different channel authentication rule. The fix for this problem was delivered in APAR IT12825 and modified MQ so that when ADOPTCTX(YES) is set, the user supplied is adopted earlier ready for checking with Channel Authentication records. Because this change could affect users who already have configured Connection Authentication and Channel Authentication, the new behavior is enabled through the attribute ChlauthEarlyAdopt under the channels stanza in the qm.ini file being set to ‘y’ or ‘Y’.

How it relates to Connection Authentication & Channel Authentication

If we assume the following scenario:

• A client application is running as UserA and supplying UserB for authentication.
• The client application will connect via a channel over TCP.
• ADOPTCTX is set to YES.
• A USERMAP Channel Authentication rule is defined to block all users.
• A USERMAP Channel Authentication rule is allow access to UserB.

With early adopt set to N (default), then the connection will be blocked. This is because despite the ADOPTCTX telling MQ to adopt the user this happens later than the USERMAP checking.

With early adopt set to Y, the connection will be permitted as UserB will be adopted earlier and used as the client user for the Channel Authentication records.

If security exits are enabled for the channel, ChlauthEarlyAdopt must be set to 'e' or 'E' otherwise the channel will fail to use the new behavior. The E option was added following the discovery that when Security Exits were in use, setting ChlauthEarlyAdopt to Y had no impact on the problem.Setting early adopt to 'e' or 'E' when security exits are not in use will have the same effect as setting it to 'y' or 'Y' and unfortunately, the E option is not available in MQ 9.0.0.0. This feature will be added via APAR IT18052 in a future fix pack.

How it relates to Channel Authentication Map rules

Unfortunately at the time of writing a defect has been discovered that means the Early Adopt feature does not work as intended when used with Mapping Rules. The way it was meant to work is as that if you had the following setup:

• A client application is running as UserA and supplying UserB for authentication.
• The client application will connect via a channel over TCP.
• ADOPTCTX is set to YES.
• A USERMAP Channel Authentication rule is defined to map UserB to UserC (1)
• A USERMAP Channel Authentication rule is defined to map UserA to UserD    (2)

When ChlauthEarlyAdopt is set to N, the USERMAP rule 2 will be triggered and cause the MCAUSER to be set to UserD. However at a later point in the security checks the ADOPTCTX(YES) will cause the MCAUSER to be set to UserB.

When ChlauthEarlyAdopt is set to Y or E, before the channel authentication rules are checked the ADOPTCTX(YES) will be triggered and UserB will be placed in the MCAUSER and set to be used for asserted User. This means when the channel authentication rules are checked USERMAP rule 1 will be triggered and UserC will be placed in the MCAUSER.

Unfortunately, this does not work currently and instead the following behavior will be seen:

When ChlauthEarlyAdopt is set to N, the behavior remains the same.

When ChlauthEarlyAdopt is set to Y or E, the behavior remains the same however before the end of the security checks ADOPTCTX(YES) triggers again and causes UserB to be placed in the MCAUSER.

Summary

In Summary, a fix delivered in 8.0.0.5 allowed users of MQ to configure when in the security process a user ID supplied for authentication was adopted. This allowed users to choose when a user ID was adopted and configure their channel authentication rules appropriately.

User ID flow diagram

Below I have included a flow diagram that may prove useful for determining which user ID will be used for channel authentication rules and authorization.

Important Note: As there is currently a defect within the early adopt feature, this flow diagram shows how MQ behaves with this defect. Once the defect is fixed i will add a second flow diagram that will show the new behavior.

There are 3 user IDs that need to be tracked in the flow diagram:

• Client user (or asserted user) – This is the user ID that the application is running as and is used for channel authentication USERMAP matching.
• Supplied User – This is the user ID that is supplied in the MQCSP structure for use with connection authentication
• MCAUSER – This is the user ID that will be used for authorization checking and ultimately shown as the user for the connection in the object status.

Conclusions

If you are implementing Connection Authentication in your MQ infrastructure, then it would be advisable to ensure that your clients and Queue Managers are all running at least 8.0.0.5 to taken advantage of the Early Adopt change and avoid the Compatibility mode bug. It is also advisable to ensure that when testing your security configuration, you test cases where a client is connecting using Compatibility mode enabled and disabled (but ensure the client is 8.0.0.3 and above).

Unless you have good reason not to (typically for historical reasons of your own), we recommend setting ADOPTCTX to yes,  ChlauthEarlyAdopt to ‘Y’ and ‘compatibility mode in MQ Explorer’ to ‘no’. That way you’ll get the most out of these authentication features. Perhaps we’ll even make the default behavior this in a future release, but don’t worry, we’ll let you know if we do!

Where to find more information

If you are looking for more information on Connection Authentication or Channel Authentication records, then you can find information and examples in both the knowledge center and on developer works blogs.

If, however, you require more assistance - you can always ask IBM for assistance using one of our numerous support channels (Advocates, Services, Email, etc). As well as IBM, there are also many third-party consulting firms who specialize in security and can be used to ensure that you are getting the most out of your IBM MQ system.

Knowledge Centre – Connection Authentication