Client side security exit to insert user ID and password ( mqccred )

If you have any client applications that are required to send a user ID or password but you are unable to change the source yet, there is a security exit shipped with IBM® MQ 8.0 called mqccred that you can use. mqccred provides a user ID and password on behalf of the client application, from a .ini file. This user ID and password are sent to the queue manager which, if configured to do so, will authenticate them.

Overview

mqccred is a security exit that runs on the same machine as your client application. It allows user ID and password information to be supplied on behalf of the client application, where that information is not being supplied by the application itself. The user ID and password information is supplied in a structure known as the Connection Security Parameters (MQCSP) and will be authenticated by the queue manager if connection authentication is configured.

User ID and password information is retrieved from a .ini file on the client machine. The passwords in the file are protected by obfuscation using the runmqccred command, and also by ensuring the file permissions on the .ini file are set such that only the user ID running the client application (and therefore the exit) are able to read it.

Location

mqccred is installed:

Windows platforms: In the <installation directory>\Tools\c\Samples\mqccred\ directory
UNIX platforms: In the <installation_directory>/samp/mqccred directory

Notes: The exit:

Acts purely as a security channel exit, and needs to be the only such exit defined on a channel.
Is usually named through the Client Channel Definition Table (CCDT), but a Java client can have the exit mentioned in the JNDI objects directly, or the exit might be configured for applications that manually construct the MQCD structure.
You must copy the mqccred and mqccred_r programs to the var/mqm/exits directory.
For example, on a 64 bit UNIX platform machine, issue the command:
```
cp <installation_directory>/samp/mqccred/lib64/* /var/mqm/exits
```
See A step by step example of how to test mqccred for more information.
Is capable of running on previous versions of IBM MQ ; as far back as Version 7.0.1.

Setting up user IDs and passwords

The .ini file contains stanzas for each queue manager, with a global setting for unspecified queue managers. Each stanza contains the name of the queue manager, a user ID, and either a plain text or obfuscated password.

You must edit the .ini file by hand, using whichever editor you want, and add the plain text password attribute to the stanzas. Run the provided, runmqccred program, which takes the .ini file and replaces the Password attribute with the OPW attribute, an obfuscated form of the password.

See runmqccred for a description of the command and its parameters.

The mqccred.ini file contains your user ID and password information.

A template .ini file is provided in the same directory as the exit to provide a starting point for your enterprise.

By default, this file will be looked for in $HOME/.mqs/mqccred.ini. If you would like to locate it elsewhere, you can use the environment variable MQCCRED to point at it:


MQCCRED=C:\mydir\mqccred.ini

If you use MQCCRED, the variable must include the full name of the configuration file, including any .ini filetype. Since this file contains passwords (even if obfuscated), you are expected to protect the file using operating system privileges to ensure unauthorized people cannot read it. If you do not have the correct file permission, the exit will not run successfully.

If the application has already supplied an MQCSP structure, the exit normally respects this and will not insert any information from the .ini file. However, you can override this by using the Force attribute in the stanza.

Setting Force to the value TRUE removes the application-supplied user ID and password, and replaces those with the ini file version.

You can also set the Force attribute in the global section of the file to set the default value of that file.

The default value for Force is FALSE.

You can provide a user ID and password for all queue managers, or for each individual queue manager. This is an example of an mqccred.ini file:


# comments are permitted
AllQueueManagers:
User=abc
OPW=%^&aervrgtsr

QueueManager:
Name=QMA
User=user1
OPW=H&^dbgfh

Force=TRUE

QueueManager:
Name=QMB
User=user2
password=passw0rd

Notes:

The individual queue manager definitions take precedence over the global setting.
Attributes are case insensitive.

Constraints

When this exit is in use, the local user ID of the person running the application does not flow from the client to the server. The only identity information available is from the ini file contents.

Therefore, you must configure the queue manager to either use ADOPTCTX(YES), or map the inbound connection request to an appropriate user ID through one of the available mechanisms, for example, Channel authentication records.

Important: If you add new passwords, or update old ones, the runmqccred command only processes any plain text passwords, leaving your obfuscated ones untouched.

Debugging

The exit writes to the standard IBM MQ trace when that is enabled.

To assist in debugging configuration issues, the exit can also write directly to stdout.

No channel security exit data ( SCYDATA ) configuration is normally required for the channel. However, you can specify:

ERROR: Only print information abut error conditions, such as not being able to find the configuration file.
DEBUG: Displays these error conditions, and some additional trace statements.
NOCHECKS: Bypasses the constraints on file permissions, and the further constraint that the .ini file should not contain any unprotected passwords.

You can put one or more of these elements into the SCYDATA field, separated by commas, in any order. For example, SCYDATA=(NOCHECKS,DEBUG).

Note that the items are case-sensitive, and must be entered in uppercase.

Using mqccred

Once you have your file set up, you can invoke the channel exit by updating your client-connection channel definition to include the SCYEXIT('mqccred(ChlExit)') attribute:


DEFINE CHANNEL(<channelname>) CHLTYPE(clntconn) +
CONNAME(<remote machine>) +
QMNAME(<remote qmgr>) +
SCYEXIT('mqccred(ChlExit)') +
REPLACE