Connection authentication with the Java client

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.

In cases where a user ID is specified, a specific authentication mode can be chosen by the application for each individual connection, or set globally before the application is started, as described in Choosing the authentication mode.

Note: Applications that use the IBM MQ classes for JMS might be affected by the change to the default authentication mode in IBM MQ 9.2.1. After upgrading the IBM MQ classes for JMS to IBM MQ 9.2.1, applications that previously used compatibility mode by default will use MQCSP authentication instead. This might cause applications that previously connected successfully to a queue manager to fail to connect with a JMSException containing reason code 2035 (MQRC_NOT_AUTHORIZED). If this occurs, use one of the methods described in Choosing the authentication mode to specify that the application uses compatibility mode.

Java applications that connect to the queue manager using local bindings always use MQCSP authentication mode.

Choosing the authentication mode

The authentication mode that is used by Java client applications that specify a user ID when connecting to the queue manager can be specified by using one of the following methods. These methods are listed in decreasing order of precedence. If the authentication mode is not specified using any of these methods, then the default authentication mode is used.

Note: The use of these methods to select the authentication mode has been clarified in IBM MQ 9.2.1. In some cases, the authentication mode used by a Java client application might change when the IBM MQ classes for Java or IBM MQ classes for JMS are upgraded to IBM MQ 9.2.1. This might cause applications that previously connected successfully to a queue manager to fail to connect with a JMSException containing reason code 2035 (MQRC_NOT_AUTHORIZED). If this occurs, use one of the following methods to select the authentication mode that is required.

• 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.
  Set the value of these properties to one of the following values:

  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.

  For more information about the useMQCSPauthentication attribute, see JMQI stanza of the client configuration file.

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.