IBM 2035 MQRC_NOT_AUTHORIZED Connecting to WebSphere MQ from WebSphere Application Server via CLIENT Bindings - United States  TECHNOTE (TROUBLESHOOTING)

PROBLEM(ABSTRACT)
 This article covers the most common reasons why an application running in WebSphere Application Server receives a 2035 MQRC_NOT_AUTHORIZED error when connecting to MQ as a client over a network. Quick steps to work around the 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, as well as inbound behavior for listener ports and activiation specifications 

SYMPTOM
JMSCMQ0001: WebSphere MQ call failed with compcode '2' ('MQCC_FAILED') reason '2035' ('MQRC_NOT_AUTHORIZED')


CAUSE
The two most likely reasons why the connection is refused by MQ are as follows: 

 1. The user identifier passed across the client connection from the application server to MQ is not known on the server where the MQ queue manager is running, is not authorised to connect to MQ, or is longer than 12 characters and has been truncated.
    We discuss how this user identifier is obtained and passed over the connection in more detail below.
    For queue managers running on Windows, the following error might be seen in the MQ error logs for this scenario:
    AMQ8075: Authorization failed because the SID for entity 'wasuser' cannot be obtained.
    For UNIX no entry in the MQ error logs would be seen by default.
    See technote MQS_REPORT_NOAUTH environment variable can be used to better diagnose return code 2035 [http://www-01.ibm.com/support/docview.wss?rs=171&uid=swg21299319] for details of enabling error log entries on all platforms. 
 2. The user identifier passed across the client connection from the application server to MQ is a member of the 'mqm' group on the server hosting the MQ queue manager, and a Channel Authentication Record (CHLAUTH) exists that blocks administrative access to the queue manager. WebSphere MQ configures a CHLAUTH record by default in WebSphere MQ Version 7.1 and later that blocks all MQ admins from connecting as a client to the queue manager.
    The following error in the MQ error logs would be seen for this scenario:
    AMQ9777: Channel was blocked

See the Error logs on Windows, UNIX and Linux systems [http://pic.dhe.ibm.com/infocenter/wmqv7/v7r5/topic/com.ibm.mq.tro.doc/q039560_.htm] section of the MQ Information Center for the location of the MQ error logs. 
DIAGNOSING THE PROBLEM
To understand the cause of the MQRC_NOT_AUTHORIZED reason code, you need to understand what username (and password) is being used by MQ to authorise the application server. 

Please note that WebSphere MQ V7.5 and earlier does not provide any out-of-the box password authentication system for client connections.
Password authentication is provided out of the box in IBM MQ V8.0. More details on the new IBM MQ V8.0 security features are available in this presentation [https://www.slideshare.net/MoragHughson/websphere-mq-v8-security-deep-dive]. 

For WebSphere MQ V7.5 and earlier, this means that while the understanding provided in this technote over how usernames/passwords are passed from the application server to MQ is helpful for development environments, solving the security requirements of production environments usually also requires one of the following approaches: 

 * Mutual SSL/TLS authentication.
   MQ provides out-of-the-box features to authenticate a remotely attaching client using the digital certificate they provide for SSL/TLS transport security. For example by configuring an SSLPEER rule on the SVRCONN channel to match the Distinguished Name in the certificate of the WebSphere Application Server, and establishing trust in the issuer of that certificate. 
 * A custom, or 3rd party supplied, WebSphere MQ Security Exit
   A security exit can be written for MQ that performs username and password authentication against a repository, such as the local operating system on the MQ server, or an LDAP repository.
   When using a security exit for authentication it is important that SSL/TLS transport security is still configured, to ensure passwords are not sent in plain text.


MCA user ID (MCAUSER) configured on the Server Connection (SVRCONN) channel If an MCAUSER is configured on the SVRCONN channel that the application server is using to connect, and no security exit or mapping Channel Authentication Record is installed, then this overrides the username provided by the application server. 

It is common practice for many customers to set an MCAUSER on every SVRCONN channel, and use mutual SSL/TLS authentication exclusively for authentication. 

Default behaviour when no credentials are supplied in 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 described below are configured, then WebSphere Application Server provides a blank username to MQ. This causes MQ to authorise the client based on the userid that the MQ listener is running under. In the majority of cases this is 'mqm' on UNIX/Linux systems and 'MUSR_MQADMIN' on Windows. 

As these are administrative MQ users, they will be blocked by default in WebSphere MQ V7.1 and higher, with a AMQ9777 error logged in the error logs of the queue manager. 

Container-managed security for outbound connections 

The recommended way to configure the username and password passed to MQ by the application server for outbound connections, is to use container-managed security. Outbound connections are those created using a Connection Factory, rather than a Listener Port or Activation Specification. 

Usernames of 12 characters or less are passed to MQ by the appliaction server. Usernames longer than 12 characters in length will be truncated, either during authorisation (on UNIX), 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 via the resource reference. For example an EJB 2.1 application would perform a JNDI lookup as follows, where "jms/MyResourceRef" has been 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 username and password contained in this authentication alias that is then passed to MQ/JMS by the application server when the application connects. This approach puts the administrator in control of which username 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 username and password. 

A default container-managed authentication alias can be supplied on the configuration panels in the administrative console for MQ connection factories. This default will only be used in the case that an application uses a resource reference configured for container-managed security, but the administrator has not bound it to an authentication alias during deployment. A screen shot is provided below:
[/support/docview.wss?uid=swg21636093&aid=1] [/support/docview.wss?uid=swg21636093&aid=1] 

Default component-managed authentication alias for outbound connections 

For cases where it is impractical to change the application to use container-managed security, or to change it to supply a username 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 via the administrative console (since WebSphere Application Server Version 7.0 when it was removed from the panels MQ connection factories). The below 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 using an activation specification an authentication alias can be specified by the administrator when deploying the application, or a default authentication alias can be specified on the activation specification via the administrative console. 

Authentication alias for inbound MDB connections using a listener port 

For inbound connections using a listener port, the value specified in the "Container-managed authentication alias" setting of the connection factory (seen in the above screenshot) is used. 

On zOS, 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: 

 1. 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. 
 2. If this user is an MQ administrative user, then relax the Channel Authentication Record (CHLAUTH) security in MQ V7.1 or higher, so that administrative connections are not blocked on the SVRCONN channel you wish to use. An example MQSC command to do this for a SVRCONN channel called 'WAS.CLIENTS' is provided as follows:
    SET CHLAUTH('WAS.CLIENTS') TYPE(BLOCKUSER) USERLIST(ALLOWANY) 
 3. Configure the SVRCONN channel to set the MCA user ID (MCAUSER) to the user you have chosen. An example MQSC command to configure a SVRCONN channel to use 'myuser' as the MCA user ID is provided as follows:
    ALTER CHL('WAS.CLIENTS') CHLTYPE(SVRCONN) MCAUSER('myuser')


The following additional considerations are important for production environments: For all production environments where transport security is required, SSL/TLS security must be configured between the application server and MQ. 

In order to configure SSL/TLS transport security, you must establish the appropriate trust between the MQ queue manager and WebSphere Application Server. The application server, who initiates the SSL/TLS handshake, must always be configured to trust the certificate provided by the MQ queue manager . If the application server is configured to send a certificate to the 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 codes after enabling SSL/TLS 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 the MQ Explorer or SSLCAUTH(REQUIRED) via MQSC. 

If you do have a security exit that performs username and password authentication installed in your 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 username and password passed to MQ by the application server are described above in the "Diagnosing the problem" section. 

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

Details of how to configure the private certificate and trust of a MQ queue manager, and to enable SSL security on a Server Connection channel, see the following locations in the MQ information center: 

 * To configure the certificates and trust of the MQ queue manager see the following topic:
   Configuring SSL on queue managers [http://publib.boulder.ibm.com/infocenter/wmqv7/v7r1/index.jsp?topic=%2Fcom.ibm.mq.explorer.doc%2Fe_ssl_channels.htm] 
 * To configure the Server Connection channel, used by applications running in the application server to connect to MQ, see the following topic:
   Configuring SSL channels [http://publib.boulder.ibm.com/infocenter/wmqv7/v7r1/topic/com.ibm.mq.explorer.doc/e_ssl_channels.htm]


Details of how you configure trust within WebSphere Application Server, and whether the application server sends a certificate to MQ for authentication, are in the following locations in the WebSphere Application Server information center:  * To create or modify an SSL Configuration containing the appropriate SSL/TLS configuration for connecting to MQ, see the following topic:
   SSL configurations [http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-base-dist&topic=csec_sslconfigs]
   Note that MQ requires you specify a matching Cipher Suite / Cipher Spec on both sides of the connection, as it checks the negotiated Cipher Suite matches the SSLCIPH setting on the channel after the handshake is complete. As a result the WebSphere Application Server SSL Configuration should be configured to contain only the Cipher Suite that matches the SSLCIPH setting on the Server Connection channel. See the following topic in the MQ information center for details of matching pairs:
   CipherSuite and CipherSpec name mappings for connections to a WebSphere® MQ queue manager [http://publib.boulder.ibm.com/infocenter/wmqv7/v7r1/topic/com.ibm.mq.msc.doc/xms_csecure_mapping_wmq.html] 
 * To enable SSL/TLS on a client connection, and choose which SSL Configuration to use, see the "Use SSL to secure communication with Websphere MQ", "Centrally managed" and "Specific configuration" sections of the following topics on Connection Factories and Activation Specifications
   WebSphere MQ messaging provider connection factory settings [http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-dist&topic=umj_pjcfm]
   WebSphere MQ messaging provider activation specification settings [http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-dist&topic=umj_pasm]

 

Cross reference information Segment Product Component Platform Version Edition Application Servers WebSphere Application Server for z/OS Java Messaging Service (JMS) z/OS, OS/390 8.5, 8.0, 7.0 Business Integration WebSphere Business Monitor AIX, HP-UX, Linux, Solaris, Windows, z/OS 7.5.1, 7.5, 7.0 Advanced, Basic Business Integration WebSphere Message Broker Environment AIX, HP-UX, Linux, Solaris, Windows, z/OS 9.0, 8.0, 7.0 Business Integration WebSphere MQ Clients AIX, HP-UX, IBM i, Linux, Windows 8.0, 7.5, 7.1, 7.0
Why do I get an exception when calling MQ after migrating my BPM environment (2035 MQRC_NOT_AUTHORIZED) ? 

We migrated our BPM environment from V8.0 to 8.5.7. When we attempt to call the MQ service we are getting the following exception:

     [10/16/17 13:50:05:273 AST] 0000026d SystemOut     O
     com.ibm.msg.client.jms.DetailedJMSSecurityException: JMSWMQ2013: The
     security authentication was not valid that was supplied for QueueManager
     'QM1' with connection mode 'Client' and host name 'MQ1(1414)'.
     Please check if the supplied username and password are correct on the
     QueueManager to which you are connecting.
     ...
     Caused by: com.ibm.mq.MQException: JMSCMQ0001: WebSphere MQ call failed
     with compcode '2' ('MQCC_FAILED') reason '2035' ('MQRC_NOT_AUTHORIZED').
      at
     com.ibm.msg.client.wmq.common.internal.Reason.createException(Reason.jav
     a:204)
      ... 162 more

The same MQ service is working fine in the old BPM environment. User name and password configured for the queue is correct. However, when we check the MQ logs, we observing the username is not used, instead the sys admin user seems to be used.
Default component-managed authentication alias for outbound connections 

For cases where it is impractical to change the application to use container-managed security, or to change it to supply a username 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 via the administrative console (since WebSphere Application Server Version 7.0 when it was removed from the panels MQ connection factories). The below 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)'