IBM Support

2035 MQRC_NOT_AUTHORIZED Connecting to WebSphere MQ from WebSphere Application Server via CLIENT Bindings

Troubleshooting


Problem

This article covers the most common reasons why an application running in WebSphere Application Server receives a 2035 MQRC_NOT_AUTHORIZED error 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 activation 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 IBM MQ are as follows:
  1. The user identifier passed across the client connection from the application server to IBM MQ is not known on the server where the queue manager is running, is not authorized to connect to IBM MQ, or is longer than 12 characters. 
  2. For queue managers running on Windows, the following error might be seen in the error logs for this scenario:
    AMQ8075: Authorization failed because the SID for entity 'wasuser' cannot be obtained.
    No entry in the error logs would be seen by default for Unix.
    See technote MQS_REPORT_NOAUTH environment variable can be used to better diagnose return code 2035 for details of enabling error log entries on all platforms.
  3. 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 queue manager, and a Channel Authentication Record (CHLAUTH) exists that blocks administrative access to the queue manager.  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 error logs would be seen for this scenario:
    AMQ9777: Channel was blocked
See the Error logs on Windows, UNIX and Linux systems section of the Information Center for the location of the 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 authorize 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.

For WebSphere MQ V7.5 and earlier, this means that while the understanding provided in this technote over how usernames and 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 behavior 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 authorize the client based on the user id that the 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 users, they will be blocked by default in WebSphere MQ V7.1 and higher, 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 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 application server. Usernames longer than 12 characters in length will be truncated, either during authorization (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:


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 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 screen shot) 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 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 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 queue manager . If the application server is configured to send a certificate to the 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 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 queue manager, and to enable SSL security on a Server Connection channel, see the following locations in the Information Center:

  • To configure the certificates and trust of the queue manager see the following topic:
    Configuring SSL on queue managers
  • 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

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:

[{"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Java Message Service (JMS)","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"8.5;8.0;7.0","Edition":"Base;Network Deployment;Single Server","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SS7K4U","label":"WebSphere Application Server for z\/OS"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Java Messaging Service (JMS)","Platform":[{"code":"PF035","label":"z\/OS"},{"code":"","label":"OS\/390"}],"Version":"8.5;8.0;7.0","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSSRR3","label":"WebSphere Business Monitor"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":" ","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"7.5.1;7.5;7.0","Edition":"Advanced;Basic","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSKM8N","label":"WebSphere Message Broker"},"Business Unit":{"code":"BU053","label":"Cloud \u0026 Data Platform"},"Component":"Environment","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"9.0;8.0;7.0","Edition":"","Line of Business":{"code":"LOB36","label":"IBM Automation"}},{"Product":{"code":"SSFKSJ","label":"WebSphere MQ"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Clients","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"8.0;7.5;7.1;7.0","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
02 March 2022

UID

swg21636093