Writing a custom interceptor: WebSphere Application Server

5.6.3: Writing a custom interceptor

If you are using a third-party reverse proxy server other than Tivoli WebSeal Version 3.6, 3.7 or 3.8, you must provide an implementation class for the WebSphere interceptor interface for your proxy server. This file describes the interface you must implement.

Using the TrustAssociationInterceptor interface

WebSphere Application Server provides the interceptor Java interface, com.ibm.websphere.security.TrustAssociationInterceptor, which defines the following methods:

public boolean isTargetInterceptor(HttpServletRequest req)
            throws WebTrustAssociationException;

public void validateEstablishedTrust(HttpServletRequest req)
            throws WebTrustAssociationException;

public String getAuthenticatedUsername(HttpServletRequest req)
            throws WebTrustAssociationException;

The isTargetInterceptor method is used to determine whether the request originated with the proxy server associated with the interceptor. The implementation code must examine the incoming request object and determine if the proxy server forwarding the request is a valid proxy server for this interceptor. The result of this method determines whether the interceptor processes the request or not.

The validateEstablishedTrust method determines if the proxy server from which the request originated is trusted or not. This method is called after the isTargetInterceptor method. The implementation code must authenticate the proxy server. The authentication mechanism is proxy-server-specific. For example, in the WebSphere-provided implementation for the WebSeal server, this method retrieves the basic-authentication information from the HTTP header and validates the information against the user registry used by WebSphere Application Server. If the credentials are invalid, the code throws the WebTrustAssociationException exception, indicating that the proxy server is not trusted and the request is to be denied.

The getAuthenticatedUsername method is called after trust has been established between the proxy server and WebSphere Application Server. WebSphere Application Server has accepted the proxy server's authentication of the request and must now authorize the request. To authorize the request, the name of the original requestor must be subjected to an authorization policy to determine if the requestor has the necessary privilege. The implementation code for this method must extract the user name from the HTTP request header and determine if that user is entitled to the requested resource. For example, in the WebSphere-provided implementation for the WebSeal server, the method looks for an iv-user attribute in the HTTP request header and extracts the user ID associated with it for authorization.

After the interceptor class has been created, WebSphere Application Server must be configured to use it by setting properties in the trustedservers.properties file. This procedure is described for the WebSeal interceptor in the InfoCenter article "Configuring trust association between WebSphere and WebSeal," and the procedure described there varies as follows:

Establish a name for your proxy to use in the WebSphere Application Server configuration properties. Use this name when you set the property com.ibm.websphere.security.trustassociation.types. For example, if you call your proxy myProxy, then set the property as follows:
```
com.ibm.websphere.security.trustassociation.types=myproxy
```
Based on the name you specified as the type of the proxy, WebSphere Application Server looks for a property that names the implementation class. Set the value of this property to the name of your implementation class. The implementation class must be locatable from the information on the class path.
The name of the property is based on the name you assigned to your proxy according to this pattern:
```
com.ibm.websphere.trustassociation.<proxyname>.interceptor
```
For example, for the proxy called myProxy, the property name is com.ibm.websphere.trustassociation.myproxy.interceptor, and for the proxy type webseal36, the property name is is com.ibm.websphere.trustassociation.webseal36.interceptor.

Making your custom interceptor configurable

To allow configuration of your custom interceptor by reading a configuration file, you can subclass the WebSphere-provided class com.ibm.websphere.security.WebSphereBaseTrustAssociationInterceptor and provide implementations of the following methods:

abstract public int init(String propsfile);
abstract public void cleanup();

The init method reads the configuration file specified for the interceptor. The configuration file is specified in the trustedservers.properties file by using a property, the name of which is determined by this pattern:

com.ibm.websphere.trustassociation.<proxyname>.config

For example, for the proxy called myProxy, the property name is com.ibm.websphere.trustassociation.myproxy.config, and for the proxy type webseal36, the property name is com.ibm.websphere.trustassociation.webseal36.config. The value of the property is the name of the configuration file for the interceptor.

The cleanup method does any necessary termination work for the interceptor.