Connection authentication with the Java client
Connection authentication is a feature in IBM® MQ that enables you to configure queue managers so that the queue manager can authenticate applications using a provided user ID and password. When the application is a Java application that is using client transport, connection authentication can be run in compatibility mode or MQCSP authentication mode.
- In an IBM MQ classes for Java application, in the MQEnvironment class, or the properties Hashtable that is passed to the com.ibm.mq.MQQueueManager constructor.
- In an IBM MQ classes for JMS application, as arguments to the createConnection(String username, String Password) or createContext(String username, String password) method.
MQCSP authentication mode
In this mode, the client-side user ID that the application runs under is sent to the queue manager, as well as the user ID and password to be authenticated. The IBM MQ classes for Java and IBM MQ classes for JMS send the user ID and password to be authenticated to the queue manager in an MQCSP structure.
The user ID and password are available to a server-connection security exit within the MQCSP structure. The MQCSP structure address can be found in the SecurityParms field of the MQCXP structure for the channel.
MQCSP authentication mode has the following benefits:
- The maximum length of the user ID to be authenticated is 1024 characters.
- The maximum length of the password for authentication is 256 characters.
- Authorization checks for access to use IBM MQ resources can be performed using the client-side user ID that the application runs under, when the authentication information object that is used to control connection authentication on the queue manager is configured with ADOPTCTX(NO).
Compatibility mode
Before IBM MQ 8.0, the Java client could send a user ID and password across the client-connection channel to the server-connection channel, and have them provided to a security exit in the RemoteUserIdentifier and RemotePassword fields of the MQCD structure. In compatibility mode, this behavior is retained.
You might use this mode in combination with connection authentication, and migrate away from any security exits that were previously used to do the same job.
This mode has the following restrictions:
- The length of the user ID and password must be 12 characters or less. User IDs longer than 12 characters are truncated to 12 characters. This might cause the connection to fail with reason code MQRC_NOT_AUTHORIZED.
- The client-side user ID that the application runs under is not sent to the queue manager. You must either set ADOPTCTX(YES) on the authentication information object that is used to control connection authentication on the queue manager, or use another method, such as a channel authentication rule based on a TLS certificate, to set the channel MCA user ID that is checked for authorization to use IBM MQ resources.
Default authentication mode
The default authentication mode that is used by an IBM MQ classes for Java or IBM MQ classes for JMS client application varies depending on whether the application specifies a user ID and a password.
From IBM MQ 9.2.1, if a user ID and password is specified, MQCSP authentication is used by default.
- In versions earlier than IBM MQ 9.2.1, if a user ID and
password is specified, the default mode is as follows:
- MQCSP authentication is used by default by applications that use IBM MQ classes for Java.
- Compatibility mode is used by default by applications that use IBM MQ classes for JMS.
- If a user ID, but no password is specified, compatibility mode is used by default.
- If no user ID is specified, compatibility mode is always used.
![[MQ 9.3.0 Jun 2022]](ng930.gif)
Java applications that connect to the queue manager using local bindings always use MQCSP authentication mode.
Choosing the authentication mode
![[MQ 9.3.0 Jun 2022]](ng930.gif)
- Specify the authentication mode for each individual connection by setting the appropriate
property in the application before connecting to the queue manager.
- When using IBM MQ classes for Java, set the property MQConstants.USE_MQCSP_AUTHENTICATION_PROPERTY in the properties Hashtable that is passed to the com.ibm.mq.MQQueueManager constructor.
- When using IBM MQ classes for JMS, set the property JmsConstants.USER_AUTHENTICATION_MQCSP on the appropriate connection factory before creating the connection.
- true
- Use MQCSP authentication mode when authenticating with a queue manager.
- false
- Use compatibility mode when authenticating with a queue manager.
- Specify the authentication mode for all client connections made by an application by setting the
com.ibm.mq.cfg.jmqi.useMQCSPauthentication
Java system property when starting the application.
Set the value of the property to one of the following values:
- Y
- Use MQCSP authentication mode when authenticating with a queue manager.
- N
- Use compatibility mode when authenticating with a queue manager.
For example, the following command sets the property to select compatibility mode and starts a Java application:java -Dcom.ibm.mq.cfg.jmqi.useMQCSPauthentication=N application_name
- Specify the authentication mode for all client connections made by applications started in the
same environment by setting the com.ibm.mq.jmqi.useMQCSPauthentication
environment variable in the environment where the application is started. Set the value of the
environment variable to one of the following values:
- Y
- Use MQCSP authentication mode when authenticating with a queue manager.
- N
- Use compatibility mode when authenticating with a queue manager.
- Specify the authentication mode for all applications that use a specific IBM MQ MQI client client configuration file by specifying the
useMQCSPauthentication attribute in the JMQI stanza of the client configuration
file. Set the value of the attribute to one of the following values:
- YES
- Use MQCSP authentication mode when authenticating with a queue manager.
- NO
- Use compatibility mode when authenticating with a queue manager.
Choosing authentication mode in IBM MQ Explorer
The IBM MQ Explorer is a Java application, so these two modes, compatibility mode and MQCSP authentication mode, are applicable to it as well.
From IBM MQ 9.1.0, MQCSP authentication mode is the default. Before IBM MQ 9.1, compatibility mode is the default.
- From IBM MQ 9.1.0, by default, this check box is not selected. To use compatibility mode, select this check box.
- Before IBM MQ 9.1.0, by default, this check box is enabled. To use MQCSP authentication, clear the check box.