Enterprise applications, the WebSphere Application Server WebSphere MQ messaging provider connection factories and Authentication Aliases explained

Answer

Enterprise applications running inside of WebSphere Application Server V7 and V8.0 that want to create a JMS connection to WebSphere MQ look up a WebSphere MQ messaging provider connection factory definition from the application server's JNDI repository and then call one of the following methods:

• ConnectionFactory.createConnection()
• ConnectionFactory.createConnection(String username, String password)

This technote explains in what situations the Authentication Alias will be used.

Connection factories and Authentication Aliases

WebSphere MQ messaging provider connection factories contain information on how to connect to WebSphere MQ queue managers. Enterprise applications running inside of WebSphere Application Server can use the connection factories to create JMS connections to WebSphere MQ.

WebSphere Application Server stores connection factories definitions in a repository that can be accessed via the Java™ Naming and Directory Interface (JNDI). When a connection factory is created, it is given a JNDI name to uniquely identify it at the application server scope (either the Cell, Node or Server scope) at which it has been defined.

For example, suppose we have a WebSphere MQ messaging provider connection factory defined at the WebSphere Application Server Cell scope that contains information on how to connect to the queue manager:

myQM

using the BINDINGS transport. This connection factory is given the JNDI name:

jms/myCF

to uniquely identify it.

Connection factories can also be configured to use an Authentication Alias. Authentication Aliases map to a username and password combination. Depending on how the connection factory is used, the username and password in the Authentication Alias may or may not be flowed down to WebSphere MQ when the JMS connection is created. We will look at this in more detail in the following sections.

Note: The default WebSphere MQ Object Authority Manager (OAM) will only perform an authorization check, to ensure that the username passed down to WebSphere MQ when a connection is made has the authority to access the queue manager. No checks are made to validate the password that is specified. In order to perform an authentication check, and validate that the user identifier and password match, you will need to write a WebSphere MQ channel security exit. Details on how to do this can be found in the Channel security exit programs section of the WebSphere MQ product documentation.

Using the connection factory - direct lookup

After a WebSphere MQ messaging provider connection factory has been defined, an enterprise application can look up the connection factory definition and use it to create a JMS connection to a WebSphere MQ queue manager.

The simplest way to do this is via a direct lookup.

To use a direct lookup, an enterprise application connects to the application server's JNDI repository by making the following method call:

InitialContext ctx = new InitialContext();

Once it has connected to the JNDI repository, the enterprise application then looks up the connection factory definition using the JNDI name of the connection factory, like this:

ConnectionFactory cf = (ConnectionFactory) ctx.lookup("jms/myCF");

There are a couple of disadvantages to this approach.

Firstly, the application developer is required to know the JNDI name of the connection factory they want to use when the enterprise application is being developed. Because the JNDI name is hard coded inside the application, if the JNDI name changes, then the application will need to be re-written and re-deployed.

The other important thing to note is that when a connection factory definition is used in this way the username and password specified in the Authentication Alias that the connection factory has been configured to use are not flowed down to WebSphere MQ. The reason for this is to prevent unauthorized applications from looking up the connection factory and being able to use it to connect to secure WebSphere MQ systems.

The actual username and password that are used depends on which method was used to create the JMS connection.

If an application creates a JMS connection using the method:

ConnectionFactory.createConnection()

then the default user identity will be passed down to WebSphere MQ. See the section entitled "The default user identity" below for more details on what this is.

The second way that applications can create a JMS connection is by calling the method:

ConnectionFactory.createConnection(String username, String password)

If an application has performed a direct lookup of a connection factory, and then called this method, then the username and password that were passed in to the createConnection() method are flowed down to WebSphere MQ.

By default, WebSphere MQ will only perform an authorization check to make sure that the username that has been flowed down has the authority to access the queue manager. No checks are made on the password. In order to perform an authentication check, and validate that the username and password are valid, a WebSphere MQ channel security exit needs to be written. Details on how to do this can be found in the Channel security exit programs section of the WebSphere MQ product documentation.

Using the connection factory - indirect lookup

If an application developer does not know the JNDI name of the connection factory they will be using when writing an enterprise application, or if the application will be installed onto different application servers and will use a different connection factory with a different JNDI name depending on what application server it is installed onto, then the connection factory can be looked up using a resource reference. This is known as an indirect lookup.

A resource reference is used to link between an application defined JNDI name and a definition stored on the application server, such as a connection factory. The resource reference has a local JNDI name, which the enterprise application looks up and uses. When the application is deployed, the resource reference is mapped to a connection factory that has been defined on the application server where the application is being deployed.

When the enterprise application is run, and looks up the connection factory using the local JNDI name, the application server will return the connection factory to which the local JNDI name was mapped. This connection factory is then used to create a connection to WebSphere MQ.

Here is an example of how this works.

Rather than directly looking up the connection factory:

jms/myCF

suppose that an enterprise application contains a resource reference that has the local JNDI name of:

jms/myResourceReferenceCF

To use this JNDI name, the application will connect to the application server's JNDI repository in the same way as if they were performing a direct lookup:

InitialContext ctx = new InitialContext();

However, rather than looking up jms/myCF directly, the application now looks up the JNDI name of the resource reference:

ConnectionFactory cf = (ConnectionFactory) ctx.lookup("java:comp/env/jms/myResourceReferenceCF");

The java:comp/env prefix at the front of the local JNDI name is needed to tell the application server that the enterprise application is performing an indirect lookup.

Now, when the application is deployed, the user maps the JNDI name of the resource reference:

jms/myResourceReferenceCF

to the JNDI name of the connection factory that they have already created:

jms/myCF

When the application is run, it looks up a JMS connection factory using the local JNDI name, which the application server maps onto:

jms/myCF

This connection factory is then used by the application to create a connection to WebSphere MQ.

Authentication Aliases and indirect lookups

A resource reference also allows additional properties to be defined that alters the behaviour of the provided connection factory. One of the properties of a resource reference is <res-auth>. The value of this property specifies whether the enterprise application should use the authentication alias of the connection factory that the resource reference maps to when creating a connection to WebSphere MQ (if an authentication alias has been defined), or if the application will specify its own username and password.

The default value of this property is Application. This means that the username and password that are flowed down to the queue manager when a JMS connection is created is determined by the application itself. The Authentication Alias of the connection factory that the resource reference maps to will not be used.

Applications can create JMS connections using one of the following methods:

ConnectionFactory.createConnection()

ConnectionFactory.createConnection(String username, String password)

If an application uses the first method shown above, and <res-auth> is set to Application, then the default user identity is flowed down to WebSphere MQ. For more details on what this is, see the section called "Default user identity" below.

If the second method is called, and <res-auth> is set to Application, the username and password passed in to the method are sent down to WebSphere MQ.

In order to use the Authentication Alias defined on the connection factory that the resource reference maps to when creating a connection, the <res-auth> property needs to be set to the value Container. When an application creates a JMS connection, the authentication alias details will be used, even if the createConnection call specifies a username and password.

Overriding the Authentication Alias when using an indirect lookup

If an application uses a resource reference that has the <res-auth> property set to Container, then it is possible to override the Authentication Alias that will be used when JMS connections are created.

To do this, the resource reference needs to include an extra property called authDataAlias, that maps to an existing Authentication Alias that has already been created in the application server environment into which the application will be deployed. The Rational tooling provided by IBM allows users to specify this property on any resource references that are created.

This feature allows application developers to use a different Authentication Alias when using a JMS connection factory that has been looked up indirectly. If the Authentication Alias specified does not exist, then a new one can be specified after the enterprise application has been installed. Details on how to do this can be found in the Resource references section of the WebSphere Application Server V8 product documentation.

The default user identity

Previously in this technote, we talked about the default user identity. This is passed down to WebSphere MQ if an application does one of the following:

• Performs a direct lookup of a connection factory, and then calls the methodConnectionFactory.createConnection()
• Performs an indirect lookup of a connection factory using a resource reference that has the <res-auth> property set to Application, and calls the method ConnectionFactory.createConnection()

Using the CLIENT transport

There is one property that overrides all of what we have talked about so far, and that is the WebSphere MQ channel agent user identifier (MCAUSER).

Connection factories that are configured to use the CLIENT transport have to specify which WebSphere MQ server connection channel (SVRCONN) they will use to connect to the queue manager.

If this property is left blank for the channel that the connection factory has been configured to use, then all of the information mentioned in this technote so far holds true and is valid.

However, if the MCAUSER property is set to a user identifier, then this user identifier is passed down to WebSphere MQ when the connection factory is used to create a connection to WebSphere MQ, regardless of whether the enterprise application is using a direct or indirect lookup.

Summary

This technote contains a lot of information on the situations in which Authentication Aliases will be used. The following tables summarize this, and provide a handy reference.

Table 2: CLIENT mode