2035 MQRC_NOT_AUTHORIZED when connecting to IBM MQ from WebSphere Application Server

The 2035 MQRC_NOT_AUTHORIZED error can occur when an application connects to IBM® MQ from WebSphere® Application Server.

This topic covers the most common reasons why an application that is running in WebSphere Application Server receives a 2035 MQRC_NOT_AUTHORIZED error when connecting to IBM MQ. Quick steps to work around the 2035 MQRC_NOT_AUTHORIZED errors during development are provided in the Resolving the problem section, as well as considerations for implementing security in production environments. A summary is also provided of behavior for outbound scenarios with container-managed and component-managed security and inbound behavior for listener ports and activation specifications.

The cause of the problem

The most common reasons for why the connection is refused by IBM MQ are described in the following list:

The user identifier that is passed across the client connection from the application server to IBM MQ is either; not known on the server where the IBM MQ queue manager is running, is not authorized to connect to IBM MQ, or is longer than 12 characters and was truncated. There is more information about how this user identifier is obtained and passed over in Diagnosing the problem.
For queue managers that are running on Windows, the following error might be seen in the IBM MQ error logs for this scenario: AMQ8075: Authorization failed because the SID for entity 'wasuser' cannot be obtained.

For AIX® and Linux®, no entry in the IBM MQ error logs would be seen.
The user identifier that is passed across the client connection from the application server to IBM MQ is a member of the mqm group on the server that hosts the IBM MQ queue manager and a channel authentication record (CHLAUTH) exists that blocks administrative access to the queue manager. IBM MQ configures a CHLAUTH record by default in IBM WebSphere MQ 7.1 and later that blocks all IBM MQ administrators from connecting as a client to the queue manager. The following error in the IBM MQ error logs would be seen for this scenario: AMQ9777: Channel was blocked.
The presence of an Advanced Message Security security policy.

For the location of the IBM MQ error logs, see Error log directories.

[MQ 9.2.1 Dec 2020] The default authentication method that is used by IBM MQ classes for JMS applications that use client transport changed from compatibility mode to MQCSP authentication in IBM MQ 9.2.1. Also, the methods that can be used to select a specific authentication mode, and which methods take precedence, has been clarified in IBM MQ 9.2.1. This might cause applications that previously connected successfully to a queue manager to fail to connect with reason code 2035 MQRC_NOT_AUTHORIZED, as the authentication method that is used by the application might change when the IBM MQ classes for Java or IBM MQ classes for JMS are upgraded to IBM MQ 9.2.1. For more information about the authentication mode used by Java clients, see Connection authentication with the Java client.

Diagnosing the problem

To understand the cause of the 2035 MQRC_NOT_AUTHORIZED reason code, you must understand which user name and password is being used by IBM MQ to authorize the application server.

Note: The understanding that is provided in this topic is helpful for development environments, solving the security requirements of production environments usually requires one of the following approaches:

Mutual SSL/TLS authentication

IBM MQ provides features to authenticate a remotely connecting client using the digital certificate that is provided for the SSL/TLS connection.
A custom, or third party supplied, IBM MQ security exit

A security exit can be written for IBM MQ that performs user name and password authentication against a repository, such as the local operating system, an IBM MQ server, or an LDAP repository. When you use a security exit for authentication it is important that SSL/TLS transport security is still configured, to ensure that passwords are not sent in plain text.

MCA user ID configured on the server connection channel

If an MCA user ID configured on the server connection channel that the application server is using to connect, and no security exit or mapping channel authentication record is installed, then the MCA user ID overrides the user name that is provided by the application server. It is common practice for many customers to set an MCA user ID on every server connection channel and use mutual SSL/TLS authentication exclusively for authentication.

Default behavior when no credentials are supplied from the application server

If no credentials are supplied by the application on the createConnection call, and neither of the component managed or container managed security systems are configured, then WebSphere Application Server provides a blank user name to IBM MQ. This causes IBM MQ to authorize the client based on the user ID that the IBM MQ listener is running under. In most cases the user ID is:

mqm on AIX or Linux systems.
MUSR_MQADMIN on Windows.

As these users are administrative IBM MQ users, they are blocked by default in IBM WebSphere MQ 7.1 and later, with an AMQ9777 error logged in the error logs of the queue manager.

Container-managed security for outbound connections

The recommended way to configure the user name and password that is passed to IBM MQ by the application server for outbound connections, is to use container-managed security. Outbound connections are those created by using a connection factory, rather than a listener port or activation specification.

User names of 12 characters or less are passed to IBM MQ by the application server. User names longer than 12 characters in length are truncated, either during authorization (on AIX and Linux), or in the MQMD of messages that are sent. Container-managed security means that the deployment descriptor, or EJB 3.0 annotations, of the application declare a resource reference with authentication type set to Container. Then, when the application looks up the connection factory in JNDI, it does so indirectly through the resource reference. For example, an EJB 2.1 application would perform a JNDI lookup as follows, where jms/MyResourceRef is declared as a resource reference in the deployment descriptor:

ConnectionFactory myCF = (ConnectionFactory)ctx.lookup("java:comp/env/jms/MyResourceRef")

An EJB 3.0 application might declare an annotated object property on the bean as follows:

@Resource(name = "jms/MyResourceRef"
      authenticationType = AuthenticationType.CONTAINER)
  private javax.jms.ConnectionFactory myCF

When the application is deployed by an administrator, they bind this authentication alias to an actual connection factory that has been created in JNDI, and assign it a J2C authentication alias on deployment. It is the user name and password that is contained in this authentication alias that is then passed to IBM MQ or JMS by the application server when the application connects. This approach puts the administrator in control of which user name and password is used by each application, and prevents a different application from looking up the connection factory in JNDI directly to connect with the same user name and password. A default container-managed authentication alias can be supplied on the configuration panels in the administrative console for IBM MQ connection factories. This default is only used in the case that an application uses a resource reference that is configured for container-managed security, but the administrator has not bound it to an authentication alias during deployment.

Default component-managed authentication alias for outbound connection

For cases where it is impractical to change the application to use container-managed security, or to change it to supply a user name and password directly on the createConnection call, it is possible to supply a default. This default is called the component-managed authentication alias and cannot be configured in the administrative console (since WebSphere Application Server 7.0 when it was removed from the panels for IBM MQ connection factories). The following scripting samples show how to configure it using wsadmin:

JACL

 wsadmin>set cell [ $AdminConfig getid "/Cell:mycell" ]
mycell(cells/mycell|cell.xml#Cell_1)
wsadmin>$AdminTask listWMQConnectionFactories $cell
MyCF(cells/mycell|resources.xml#MQConnectionFactory_1247500675104)
wsadmin>$AdminTask modifyWMQConnectionFactory MyCF(cells/mycell|resources.xml#MQConnectionFactory_1247500675104) { -componentAuthAlias myalias }
MyCF(cells/mycell|resources.xml#MQConnectionFactory_1247500675104)

Jython

wsadmin>cell = AdminConfig.getid("/Cell:mycell")
wsadmin>AdminTask.listWMQConnectionFactories(cell)
'MyCF(cells/mycell|resources.xml#MQConnectionFactory_1247500675104)'
wsadmin>AdminTask.modifyWMQConnectionFactory('MyCF(cells/mycell|resos   urces.xml#MQConnectionFactory_1247500675104)', "-componentAuthAlias myalias")
'MyCF(cells/mycell|resources.xml#MQConnectionFactory_1247500675104)'

Authentication alias for inbound MDB connections using an activation specification

For inbound connections that use an activation specification, an authentication alias can be specified by the administrator when the application is deployed, or a default authentication alias can be specified on the activation specification in the administrative console.

Authentication alias for inbound MDB connections using a listener port

For inbound connections that use a listener port, the value that is specified in the container-managed authentication alias setting of the connection factory is used. [z/OS] On z/OS®, first the container-managed authentication alias is checked and used if set, then the component-managed authentication alias is checked and used it set.

Resolving the problem

The simplest steps to resolve the 2035 MQRC_NOT_AUTHORIZED errors in a development environment, where full transport security is not required, are as follows:

Choose a user that you want WebSphere Application Server to be authenticated as. Typically the user chosen should have authority relevant to the context of the operations required by the application running in WebSphere Application Server and no more. For example, mqm or other super user is not appropriate.
If this user is an IBM MQ administrative user, then relax the channel authentication record (CHLAUTH) security in IBM WebSphere MQ 7.1 or later so that administrative connections are not blocked on the server connection channel you want to use. An example MQSC command for a server connection channel called WAS.CLIENTS is, SET CHLAUTH('WAS.CLIENTS') TYPE(BLOCKUSER) USERLIST(ALLOWANY).
Configure the server connection channel to set the MCA user ID (MCAUSER) to the user you are using. An example MQSC command to configure a server connection channel to use myuser as the MCA user ID is, ALTER CHL('WAS.CLIENTS') CHLTYPE(SVRCONN) MCAUSER('myuser').

Important extra considerations for production environments

For all production environments where transport security is required, SSL/TLS security must be configured between the application server and IBM MQ.

To configure SSL/TLS transport security, you must establish the appropriate trust between the IBM MQ queue manager and WebSphere Application Server. The application server initiates the SSL/TLS handshake and must always be configured to trust the certificate that is provided by the IBM MQ queue manager. If the application server is configured to send a certificate to the IBM MQ queue manager, then the queue manager must also be configured to trust it. If trust is not correctly configured on both sides, you will encounter 2393 MQRC_SSL_INITIALIZATION_ERROR reason code after SSL/TLS is enabled on the connection.

If you do not have a security exit that performs username and password authentication, then you should configure mutual SSL/TLS authentication on your server connection channel to cause the queue manager to require a trusted certificate is provided by the application server. To do this you set SSL Authentication to Required in IBM MQ Explorer or SSLCAUTH(REQUIRED) in MQSC.

If you do have a security exit that performs user name and password authentication that is installed in your IBM MQ server, then configure your application to supply a username and password for validation by that security exit. The details of how to configure the user name and password that is passed to IBM MQ by the application server are described previously in the Diagnosing the problem section.

All server connection channels that do not have SSL/TLS security should be disabled. Example MQSC commands to disable the SYSTEM.DEF.SVRCONN channel are provided as follows (assuming no user exists on the IBM MQ server called ('NOAUTH'), ALTER CHL(SYSTEM.DEF.SVRCONN) CHLTYPE(SVRCONN) MCAUSER('NOAUTH') STOP CHL(SYSTEM.DEF.SVRCONN).

For instructions to configure the private certificate and trust of an IBM MQ queue manager and to enable SSL security on a server connection channel, see Configuring SSL on queue managers and Configuring SSL channels.

For information about using SSL/TLS from WebSphere Application Server and whether the application server sends a certificate to IBM MQ for authentication, see the following information:

To create or modify an SSL configuration to contain the appropriate SSL/TLS configuration for connection to IBM MQ, see SSL configurations in the WebSphere Application Server product documentation.
It is required by IBM MQ that you must specify a matching CipherSpec on both ends of the connection. For more information about CipherSpecs and CipherSuites that can be used with IBM MQ, see CipherSuite and CipherSpec name mappings for connections to an IBM MQ queue manager.
For more information about enabling SSL/TLS on a client connect and choosing which SSL configuration to use, see WebSphere MQ messaging provider connection factory settings and WebSphere MQ messaging provider activation specification settings in the WebSphere Application Server product documentation.