WebSphere MQ security exit

TrueSight Middleware Administrator provides MQ security exits that can be used to temporarily override user information kept with the receiving server connection channel (such as the MCAUserIdentifier) with credentials users must provide when requesting access to messaging operations on a target z/OS queue manager. This allows authenticating or auditing these requests against an individual user's profile on the target z/OS system using a system access facility like RACF.

Note that PCF communication to interact with MQ objects (for example, to display an object's properties) will continue to be executed under the general userid supplied as part of the WMQ Connection definition within TrueSight Middleware Administrator.

Specifically, TrueSight Middleware Administrator provides a server-side WMQ security exit for z/OS and a client-side security exit for Linux. These must be used on both ends of the channel consistently when setting up a WMQ connection within TrueSight Middleware Administrator to a target z/OS queue manager which will be secured by this exit.

When the security exit configuration is enabled, the TrueSight Middleware Administrator Server forms a separate connection per user for message management (Put/Get/Browse) operations. When first accessing these operations, the user will be prompted for the credentials to be used on z/OS.

The 'server side' of the TrueSight Middleware Administrator security exit resides on the system hosting the target (z/OS) queue manager and is associated to the server connection channel used for connecting the queue manager to TrueSight Middleware Administrator. The server-side exit's purpose is to 'switch' the user context on the queue manager side for the new connection established through TrueSight Middleware Administrator so that the user supplied credentials are authenticated through a system access facility (e.g. RACF) for MQ messaging operations. 'Switching the user context within the context of WebSphere MQ' means the server-side exit temporarily changes the 'MCAUserIdentifier' in the channel descriptor (MQCD) of the server connection channel to the credentials the requesting user has provided (temporarily overriding any setting configured with the server connection channel) and also adjusts - if not already done internally by WMQ itself - the MQCD fields 'RemoteUserIdentifier' and 'RemotePassword' per the user credentials provided.

The 'client side' of the TrueSight Middleware Administrator security exit resides on the Linux system where TrueSight Middleware Administrator was installed and must be associated to the WMQ client connection channel used for connecting the TrueSight Middleware Administrator services to the target z/OS queue manager. The purpose of the client-side exit is to manage exit communications and ensure that the supplied credentials are actually being applied by a properly configured server-side security exit.

The following sections describe how to secure TrueSight Middleware Administrator connections using the TrueSight Middleware Administrator security exit. 

Resources

On the client/TrueSight Middleware Administrator side

bmcacsx - 64-bit WebSphere MQ security exit library (Linux)

On the server/queue manager side

RECEIVE - z/OS RECEIVE Job
TSMA.BMCACSX.LOADLIB.XMIT - XMIT file for the z/OS security exit load library

Requirements

Supported platforms

• Client (TrueSight Middleware Administrator) side: Linux (RHEL 7.x or higher, CentOS 7.x or higher)
• Server (queue manager) side: z/OS 2.2 or higher

Software requirements

• Client/TrueSight Middleware Administrator:
  
  • Recommended: WebSphere MQ 8.0 (client installation) or higher
  • Minimum: WebSphere MQ 7.1 (client installation) or higher.

• Server/queue manager:
  • Recommended: WebSphere MQ 8.0 or higher
  • Minimum: WebSphere MQ 7.1 or higher

Installing the security exits

To install on the server side (for target z/OS queue managers)

1. Transmit the resources (RECEIVE and TSMA.BMCACSX.LOADLIB.XMIT) to the target z/OS system, with FTP for example. 
   1. From the directory containing the resource (TrueSight Middleware Administrator installdir>/etc/exits/zos), connect with FTP to the target z/OS system, switch to ASCII mode by entering ascii, and preallocate the dataset for the RECEIVE job entering quote site TR lrecl=80 recfm=fb blksize=800 primary=1 secondary=1.
   2. Transfer RECEIVE to the z/OS system with a High Level Qualifier of your choice: put RECEIVE '<HLQ>.RECEIVE', and switch to binary transfer mode by entering bin. Then pre-allocate the target dataset for TSMA.BMCACSX.LOADLIB.XMIT with quote site CY lrecl=80 recfm=fb blksize=3120 primary=2 secondary=5.
   3. Transfer TSMA.BMCACSX.LOADLIB.XMIT to the z/OS system with a High Level Qualifier of your choice. Put TSMA.BMCACSX.LOADLIB.XMIT '<HLQ>.TSMA.BMCACSX.LOADLIB.XMIT'.
   4. Quit the FTP connection.
2. Build the TrueSight Middleware Administrator security exit:
   1. Customize the RECEIVE job to suit your requirements.
   2. Submit the RECEIVE job after saving your changes.
3. Deploy the TrueSight Middleware Administrator security exit to the target WMQ queue manager by adding to <MQ>CHIN the DD statement below with the adjusted high level qualifier: 
   //CSQXLIB  DD DISP=SHR,DSN=<HLQ>.TSMA.BMCACSX.LOADLIB
4. Set up (RACF) security for the target queue manager:
   1. To make use of the security exit's functionality with an external security manager such as RACF, set up security in WebSphere MQ for z/OS to ensure the account the queue manager is running under (the 'started task user') and also the user account configured for the related TrueSight Middleware Administrator WMQ connection are both 'privileged' to access all resources. This is because the user account used with the TrueSight Middleware Administrator WMQ connection is the default account used to access all WMQ resources on the target z/OS queue manager through TrueSight Middleware Administrator.
      Refer to the IBM WebSphere MQ product documentation for details on setting up security in WebSphere MQ on z/OS.
   2. With the security exit feature enabled, users will be prompted to provide credentials when requesting messaging operations on the target z/OS queue manager and the security exit will 'switch' the context of the connection according to the credentials the user provides by resetting user information in the MQCD, such as the MCAUSER. This causes messaging operations to be processed 'on behalf' of that user. This must be taken into consideration when setting up security for WebSphere MQ; you must assign each user the proper messaging and queue access permissions. You must also permit the default user account configured for the TrueSight Middleware Administrator WMQ connection to switch the context.

To install on the client side (the TrueSight Middleware Administrator installation)

1. Ensure TrueSight Middleware Administrator is running with the WebSphere MQ environment set up properly for use with WebSphere MQ for Java and WebSphere MQ for JMS:
   1. Run 'setjmsenv64' to set up the WebSphere MQ environment.
   2. Run 'dspmqver -p4' to verify.
2. Stop TrueSight Middleware Administrator services.
3. The client side security exit for Linux by default is installed to the directory <TrueSight Middleware Administrator_installdir>/etc/exits/linux-x86-64/ and can be used from that directory, but can optionally be copied to any location better suited.
4. Make the exit library executable in the proper environment (for example, by running chmod a+x).
5. Add bmcacsx to the TrueSight Middleware Administrator classpath. To do this, edit <TrueSight Middleware Administrator_installdir>/configuration/wrapper.conf by adding another entry for wrapper.classpath.java pointing to the exit library, e.g wrapper.java.classpath.3=/etc/exits/Linux-x86-64/bmcacsx. Save your changes and close the editor. 
6. Start TrueSight Middleware Administrator services. 

Configuration

Configuring TrueSight Middleware Administrator

To make use of the functionality provided by the security exits within TrueSight Middleware Administrator this feature needs to be enabled within the TrueSight Middleware Administrator configuration. To do so, perform the following steps:

1. Stop TrueSight Middleware Administrator services.
2. Edit the configuration/wrapper.conf file and add an entry for setting the system property MSG_AUTH_RACF to true, such as wrapper.java.additional.<nn>=-DMSG_AUTH_RACF=true, where <nn> needs to be replaced with the number following the highest of related existing entries (e.g. wrapper.java.additional.22).
3. Save the configuration changes.
4. Start TrueSight Middleware Administrator services.
5. Login to the Admin Console.
6. Edit all WMQ Connections referring to a z/OS queue manager and select the z/OS Queue Manager checkbox for each. Save the change to each WMQ Connection. 
   This enables logged in users to be prompted to provide user credentials (username and password) when requesting messaging operations on an enabled z/OS queue manager. These credentials are valid and cached (but not persisted) per user session so users need to re-enter their credentials the next time they login.

Configuring security exits on the server side

For the target z/OS queue managers you plan to use with the TrueSight Middleware Administrator security exit do the following:

• Make the server side exit available on the z/OS queue manager (see To install on the server side (for target z/OS queue managers) above).
• Configure the server side TrueSight Middleware Administrator security exit for the related server connection channels dedicated to TrueSight Middleware Administrator to connect to the queue manager.  
• In the channel’s ‘Security Exit’ entry enter: 'BMCACSX’.

Configuring security exits on the client side

1. Login to the TrueSight Middleware Administrator Web UI as a Product Administrator.
2. Make sure the WebSphere MQ connection you want to use the security exit with is not in use (by setting the related server connection channel to inactive).
3. Switch to the Admin Console and select the relevant WebSphere MQ connection you want to use the client side exit with.
4. Edit the WMQ connection you want to use the client side exit with. If the exit is located in a subfolder of the TrueSight Middleware Administrator installation directory, enter the (relative) path to the client-side exit into the Security Exit Library Name field (for example: etc/exits/linux-x86-64/bmcacsx).
5. Enter 'ChannelExit' in the Security Exit Entry Point field.
6. Select the Security Exit Enabled checkbox.
7. Save your changes for the WMQ connection.