The WebSphere Everyplace Suite (WES) communications adapter

WebSphere MQ Everyplace provides sophisticated security that allows applications to run over HTTP, through the protection of an Internet firewall. The purpose of the WebSphere Everyplace communications adapter is to allow WebSphere MQ Everyplace applications to authenticate themselves with the WebSphere Everyplace authentication proxy and thus allow messages to flow through it. Figure 2 shows a basic scenario with two applications communicating over the Internet through the WebSphere Everyplace authentication proxy.

Figure 2. Applications communicating through the WebSphere authentication proxy

Diagram showing two WebSphere MQ Everyplace applications communicating through the WebSphere Authentication Proxy. The sending application uses an adapter called 'Auth HTTP' and the receiving application uses an adapter called 'HTTP'with the WebSphere Authentication Proxy between the two adapters.

The WebSphere MQ Everyplace adapter acts as the Auth HTTP adapter on the sending application. The receiving application could use either the same adapter or the standard HTTP adapter provided with WebSphere MQ Everyplace.

However, the real value of WebSphere MQ Everyplace is that it allows asynchronous messaging to occur in a typically synchronous environment. It is possible to gather enqueued requests from the receiving application and deal with them time-independently. Figure 3 shows how incoming requests could be made to reach WebSphere MQ servers asynchronously.

Figure 3. Applications communicating asynchronously through the WebSphere Authentication Proxy

Diagram showing WebSphere MQ Everyplace applications communicating asynchronously through the WebSphere Authentication Proxy, and then passing the messages over a WebSphere MQ Everyplace-WebSphere MQ bridge to a WebSphere MQ queue manager. The sending application uses an adapter called 'Auth HTTP' and the receiving enqueueing application uses an adapter called 'HTTP' with the WebSphere Authentication Proxy between the two adapters. A WebSphere MQ Everyplace dequeueing application passes the messages to a WebSphere MQ Everyplace-WebSphere MQ bridge bridge which connects to the WebSphere MQ queue manager.

In each of these environments the WebSphere authentication proxy is adding the ability to control access to the receiving applications. The adapter code supports this by adding (application-supplied) user ID and password information to each outgoing HTTP request. The WebSphere authentication proxy accepts these requests and verifies that the supplied credentials are valid for the current environment. If the credentials are valid the proxy forwards the request to the receiving application.

The WebSphere Everyplace adapter files

In a standard WebSphere MQ Everyplace installation the WebSphere Everyplace adapter consists of, and is supported by the following files:

...\Java\com\ibm\mqe\adapters\MQeWESAuthenticationAdapter.class
- The WebSphere Everyplace adapter class.

...\Java\examples\application\Example7.class
- Compiled example application that uses the adapter

...\Java\examples\application\Example7.java
- Source for the example application

...\Java\examples\adapters\WESAuthenticationGUIAdapter.class
- Compiled example adapter that adds a user interface to the WebSphere Everyplace adapter. As with other example classes, this class is not meant as a replacement for the base WES adapter class, but rather as a demonstration of how to tailor the WES adapter to suit your requirements.

...\Java\examples\adapters\WESAuthenticationGUIAdapter.java
- Source for the example adapter

If your environment CLASSPATH variable is set to find all classes within the WebSphere MQ Everyplace Java folder, the WebSphere Everyplace adapter class files should be accessible from within the Java environment. If the files are not accessible, issue a command such as:

set CLASSPATH=%CLASSPATH%;c:\mqe\java

This will make the new classes visible to Java. (The exact format of this command may vary from system to system.) Once this is complete you should be able to use the WebSphere Everyplace adapter classes in the same way as any other WebSphere MQ Everyplace classes.

Using the WebSphere Everyplace adapter

This section provides information on how to use the WebSphere Everyplace adapter. The information is divided into three parts:

General operation
This describes in detail, how to use the adapter in your applications

Using the Authentication Dialog Example
This describes how to use an example class, examples.adapters.WESAuthenticationGUIAdapter. This class is derived from the base WES adapter class and provides a small user interface to collect the ID and password of the user.

Using the Application Example
This describes how to use the supplied example file examples.application.Example7 which is configured to use the base WES adapter.

The information in this section assumes that both the WebSphere Everyplace authentication proxy and WebSphere MQ Everyplace have been installed and configured correctly. It is also assumed that an WebSphere MQ Everyplace server queue manager and an WebSphere MQ Everyplace client queue manager have been configured.

General Operation

  1. Configure the client queue manager to send messages using the new adapter by modifying the client queue manager's configuration .ini file so that the Network alias points to com.ibm.mqe.adapters.MQeWESAuthenticationAdapter. Use the following command:
    (ascii)Network=com.ibm.mqe.adapters.MQeWESAuthenticationAdapter
    
  2. Configure the server queue manager to decode the stream of data that the Client Adapter supplies using either the new adapter or the standard HTTP adapter. Do this by changing the line in the server queue manager's configuration .ini file so that the Network alias points to either com.ibm.mqe.adapters.MQeWESAuthenticationAdapter or com.ibm.mqe.adapters.MQeTcpipHttpAdapter. Use one of the following commands:
    (ascii)Network=com.ibm.mqe.adapters.MQeWESAuthenticationAdapter	
    
    (ascii)Network=com.ibm.mqe.adapters.MQeTcpipHttpAdapter
    
  3. Modify the client queue manager code so that the required user ID and password are set before the first network operation is started. For example, insert the following line near the top of your code:
    com.ibm.mqe.adapters.MQeWESAuthenticationAdapter.
    setBasicAuthorization("myUserId@myRealm", "myPassword");
    
    Replace the parameters with a valid WES Server user ID and password.

    You also need to add code to catch the new MQeException Except_Authenticate after each network operation, in case the supplied credentials were invalid.

  4. Check that the client queue manager can still send messages to the server queue manager without going through the proxy.
  5. Configure the client machine to send HTTP requests through the proxy. Depending on how WES has been configured, the adapter will need to work with either a transparent proxy or an authentication proxy.

    As a transparent proxy
    In this mode, the WES server acts as a simple HTTP proxy. In this case, you need to set the following Java application system properties that relate to proxy information:

    http.proxyHost
    Must be set to the host name of the WES proxy

    http.proxyPort
    Must be set to the name of the port that the proxy is listening on

    http.proxySet
    Must be set to true, which tells the adapter to use transparent proxy mode

    The above parameters can be set by adding the following to your Java application:

      System.getProperties( ).put( "http.proxySet",  "true" );
    	System.getProperties( ).put( "http.proxyHost", "wes.hursley.ibm.com" );
    	System.getProperties( ).put( "http.proxyPort", "8082" );
     
    

    The client queue manager's connection to the target WebSphere MQ Everyplace server is similar to a connection that doesn't use the WES proxy.

    Figure 4. Administration interface panel

    Screen capture showing Administration interface panel with connection details.

    You need to restart the server and client queue managers for the new settings to take effect. The client should then be able to send messages to the server through the proxy.

    As an Authentication Proxy
    In this mode, the WES server forwards requests to services, based on the URL that you supply. For example, you may want requests for http://wes.hursley.ibm.com/mqe to be forwarded to an WebSphere MQ Everyplace queue manager running on mqe.hursley.ibm.com:8082.

    To set this up from WebSphere MQ Everyplace you need to update the client's connection reference to the server.

    Target network adapter
    Should point to the Authentication Proxy machine and port

    Network adapter parameters
    Should contain the pathname to the required service

    If you are using the WebSphere MQ Everyplace Example Administration tool, select Connection and then Update to configure this.

    Figure 5. Administration interface panel

    Screen capture of the administration interface Update panel showing connection details.

    Note:
    The reference to the WES Server is entered in the Network adapter field, and the pathname is entered in the Network adapter parms field.
    You need to restart the server and client queue managers for the new settings to take effect. The client should then be able to send messages to the server through the proxy.

Using the Authentication Dialog Example

The following information describes the use of the example class file, examples.adapters.WESAuthenticationGUIAdapter. This class adds a small user interface to the base WES adapter function.

  1. Follow steps (1) and (2) of the 'General operation' procedures, but substitute 'WESAuthenticationGUIAdapter' for 'WESAuthenticationAdapter' in step (1).
  2. Configure the client's TCP/IP settings as in step (5) of 'General operation'.

Figure 6. WebSphere Everyplace Suite adapter user dialog

WebSphere MQ Everyplace Suite adapter user login dialog.

The client should now able to send messages to the server using the WESAuthenticationGUIAdapter. This adapter intercepts write calls to the WES adapter, and on the first request it pops up a dialog box that prompts for user ID and password information.

When the user clicks on OK or presses the Enter key, the setBasicAuthorization() method is called with the values from the userid and password fields. The write() is then forwarded on to the underlying WES adapter. The dialog box also has a Cancel button which, when selected, cancels the current write operation by not forwarding the request to the WES adapter. This causes an MQeException (Except_Stopped) to be thrown.

If authentication fails, the dialog box is redisplayed on the next write() along with any information provided by the server. In order to learn of an authentication failure, the example adapter intercepts read() calls and catches any Except_Authenticate MQeExceptions coming from the adapter.

Note:
Web browsers do not generally send authentication information on the first flow. This typically results in a 401 or 407 response that contains the realm information. Only then does the browser send the authenticated request. User clients may wish to follow this convention.

Using the Application Example

The following information describes the use of the example application file, examples.application.Example7. This example behaves in a similar way to the MQSeries Everyplace programming example examples.application.Example1 and uses the basic WES adapter for communications.

  1. Follow steps (1) and (2) of the 'General operation' procedures.
  2. Configure the client's TCP/IP settings as in step (5) of 'General operation'.
  3. Edit the example file ...\Java\examples\application\Example7.java inserting a valid user ID and password, and then recompile the application.
  4. Restart the server.
  5. Run the Example7 program using the following command:
    java examples.application.Example7 Server client.ini
    
    where

    Server
    is the name of the remote queue manager (that the client already knows how to reach)

    client.ini
    points to the client's .ini configuration file.
    The application starts the client queue manager, authenticates with the proxy, puts a message to server and then get a message from the server.


© IBM Corporation 2002. All Rights Reserved