150 lines
12 KiB
HTML
150 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<LINK rel="stylesheet" type="text/css" href="../../../rzahg/ic.css">
|
|
|
|
<title>Develop a custom interceptor for trust associations</title>
|
|
</head>
|
|
|
|
<BODY>
|
|
<!-- Java sync-link -->
|
|
<SCRIPT LANGUAGE="Javascript" SRC="../../../rzahg/synch.js" TYPE="text/javascript"></SCRIPT>
|
|
|
|
<h3><a name="secdint.htm"></a>Develop a custom interceptor for trust associations</h3>
|
|
|
|
<p>If you are using a third-party reverse proxy server other than Tivoli WebSeal Version 3.6, you must provide an implementation class for the WebSphere Application Server - Express interceptor interface for your proxy server. This topic describes the interface you must implement.</p>
|
|
|
|
<ol>
|
|
<li><p>Define the interceptor class method.
|
|
<br>WebSphere Application Server - Express provides the interceptor Java interface, <a href="../program/apidocs/ae/com/ibm/websphere/security/TrustAssociationInterceptor.html">com.ibm.websphere.security.TrustAssociationInterceptor</a> <img src="api.gif" width="18" height="15" align="absbottom" alt="Go to API documentation"> which defines these methods:</p>
|
|
|
|
<ul>
|
|
<li><p><strong>isTargetInterceptor(HttpServletRequest req)</strong>
|
|
<br>The isTargetInterceptor() method determines if the request originated with the proxy server that is associated with the interceptor. The implementation code examines the incoming request object and determines if the proxy server that is forwarding the request is a valid proxy server for this interceptor. The result of this method determines if the interceptor processes the request or not.</p></li>
|
|
|
|
<li><p><strong>validateEstablishedTrust(HttpServletRequest req)</strong>
|
|
<br>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 specific to the proxy server. For example, in the WebSphere implementation that is provided for the WebSeal server, this method retrieves the basic authentication information from the HTTP header and validates the information against the user registry that is used by WebSphere Application Server - Express. If the credentials are invalid, the method throws the WebTrustAssociationException exception, which indicates that the proxy server is not trusted and the request is to be denied.</p></li>
|
|
|
|
<li><p><strong>getAuthenticatedUsername(HttpServletRequest req)</strong>
|
|
<br>The getAuthenticatedUsername method is called after trust has been established between the proxy server and WebSphere Application Server - Express. WebSphere Application Server - Express 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 requester must be subjected to an authorization policy to determine if the requester has the necessary authorities. 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.</p></li>
|
|
</ul><p></p></li>
|
|
|
|
<li><p>Set properties in the trustedservers.properties file.
|
|
<br>To be configurable, the interceptor must extend com.ibm.websphere.security.WebSphereBaseTrustAssociationInterceptor. Implement these methods:</p>
|
|
|
|
<ul>
|
|
<li><p><strong>init(java.util.Properties props)</strong>
|
|
<br>The init(Properties) method accepts a java.util.Properties object, which contains the set of properties required to initialize the interceptor. All the properties set for an interceptor (by using the <strong>Custom Properties</strong> link for that interceptor or using scripting) is sent to this method. The interceptor then can use these properties to initialize itself. For example, in the product implementation for the WebSEAL server, this method reads the hosts and ports so that a request coming in can be verified to originate from trusted hosts and ports. A return value of <tt>0</tt> implies that the interceptor initialization is successful. Any other value implies that the initialization is not successful and the interceptor is ignored.</p>
|
|
|
|
<p><strong>Version 5.0.2 or later:</strong> If a previous implementation of the trust association interceptor returns a different error status you can either change your implementation to match the expectations or make one of the following changes:</p>
|
|
<ul>
|
|
<li><p>Add the com.ibm.websphere.security.trustassociation.initStatus property in the trust association interceptor custom properties. Set the property to the value that indicates that the interceptor is successfully initialized. All of the other possible values imply failure. In case of failure, the corresponding trust association interceptor is not used.</p></li>
|
|
<li><p>Add the com.ibm.websphere.security.trustassociation.ignoreInitStatus property in the trust association interceptor custom properties. Set the value of this property to <tt>true</tt>, which tells WebSphere Application Server to ignore the status of this method. If you add this property to the custom properties, WebSphere Application Server does not check the return status, which is similar to previous versions of WebSphere Application Server.</p></li>
|
|
</ul></li>
|
|
|
|
<li><p><strong>cleanup()</strong>
|
|
<br>The cleanup method is called when the application server is stopped. It can be used to prepare the interceptor for termination.</p></li>
|
|
|
|
<li><p><strong>setVersion (String s)</strong>
|
|
<br>The setVersion method is optional. It sets the version and is for informational purposes only. The default value is <tt>Unspecified</tt>.</p></li>
|
|
</ul>
|
|
<p>To make your custom interceptor configurable, perform these steps:</p>
|
|
<ol type="a">
|
|
<li><p>Configure these methods implemented by the custom interceptor implementation.</p>
|
|
<p><strong>Note:</strong> This list only shows the methods and does not include any implementation.</p>
|
|
<pre>import java.util.*;
|
|
import javax.servlet.http.HttpServletRequest;
|
|
import com.ibm.websphere.security.*;
|
|
|
|
public class myTAIImpl extends WebSphereBaseTrustAssociationInterceptor
|
|
implements TrustAssociationInterceptor {
|
|
|
|
public myTAIImpl () {
|
|
}
|
|
|
|
public boolean isTargetInterceptor (HttpServletRequest req)
|
|
throws WebTrustAssociationException {
|
|
// Return true if this is the target interceptor, else return false.
|
|
}
|
|
|
|
public void validateEstablishedTrust (HttpServletRequest req)
|
|
throws WebTrustAssociationFailedException {
|
|
// Validate if the request is from the trusted proxy server.
|
|
// Throw exception if the request is not from the trusted server.
|
|
}
|
|
|
|
public String getAuthenticatedUsername (HttpServletRequest req)
|
|
throws WebTrustAssociationUserException {
|
|
// Get the user name from the request and if the user is
|
|
// entitled to the requested resource return the user.
|
|
// Otherwise, throw the exception.
|
|
}
|
|
|
|
public int init (Properties props) {
|
|
// Initialize the implementation. If successful return 0, else return -1.
|
|
}
|
|
|
|
public void cleanup () {
|
|
// Cleanup code.
|
|
}
|
|
}</pre></li>
|
|
|
|
<li><p>Previous versions of com.ibm.websphere.security.WebSphereBaseTrustAssociationInterceptor include the <tt>public int init(String propsfile)</tt> method. This method is no longer required becasue the interceptor properties are not read from a file. The properties are now entered with the administrative console (in the <strong>Custom Properties</strong> section of the interceptor) or with scripts. These properties then are made available to your implementation in the init(Properties) method. However, for backward compatibility, the init(String) method still is supported. The init(String) method is called by the default implementation of init(Properties) as shown in the following example:</p>
|
|
|
|
<p><strong>Note:</strong> If your custom interceptor implements the init(Properties) method as described previously, you do not need to call the init(String). You can continue to the next step.</p>
|
|
|
|
<pre>// Default implementation of init(Properties props) method. A Custom
|
|
// implementation should override this.
|
|
public int init (java.util.Properties props) {
|
|
String type =
|
|
props.getProperty("com.ibm.websphere.security.trustassociation.types");
|
|
String classfile =
|
|
props.getProperty("com.ibm.websphere.security.trustassociation."
|
|
+ type
|
|
+ ".config");
|
|
if (classfile != null && classfile.length() > 0 ) {
|
|
return init(classfile);
|
|
} else {
|
|
return -1;
|
|
}
|
|
}</pre>
|
|
|
|
<p>Change your implementation to implement the init(Properties) method instead of the init(String propsfile) method. As shown in the previous example, this default implementation reads the properties to load the property file. To determine the properties file that it must read, the com.ibm.websphere.security.trustassociation.types property appends <tt>.config</tt> to its value.</p>
|
|
|
|
<p><strong>Note:</strong> The init(String) method still works if you want to use it instead of implementing the init(Properties) method. The only requirement is that the name of the file that contains the custom trust association properties should now be entered using the <strong>Custom Properties</strong> link of the interceptor in the administrative console or by using scripts. You can enter the property using either of the following methods. The first method is used for backward compatibility with previous versions of WebSphere Application Server:</p>
|
|
<ul>
|
|
<li><p>The same property names used in the previous release are used to obtain the file name. The file name is obtained by concatenating the <tt>.config</tt> extension to the com.ibm.websphere.security.trustassociation.types property value. If the file name is called myTAI.properties and is located in the /QIBM/UserData/WebASE/ASE5/myInstance/properties directory, set the following properties:</p>
|
|
<pre>com.ibm.websphere.security.trustassociation.types = myTAItype
|
|
com.ibm.websphere.security.trustassociation.myTAItype.config =
|
|
/QIBM/UserData/WebASE/ASE5/myInstance/properties/myTAI.properties</pre></li>
|
|
<li><p>You can set the com.ibm.websphere.security.trustassociation.initPropsFile property in the trust association custom properties to the location of the file. For example, set the following property:</p>
|
|
<pre>com.ibm.websphere.security.trustassociation.initPropsFile=
|
|
/QIBM/UserData/WebASE/ASE5/myInstance/properties/myTAI.properties</pre></li>
|
|
</ul>
|
|
|
|
<p><strong>Note:</strong> These properties have been wrapped for display purposes. Type them as one continuous line.</p></li>
|
|
|
|
<li><p>Compile the implementation. Make sure that wssec.jar and j2ee.jar are in the compiler class path. These JAR files are located in the /QIBM/ProdData/WebASE/ASE5/lib directory.</p></li>
|
|
|
|
<li><p>Create a <tt>classes</tt> subdirectory in the /QIBM/UserData/WebASE/ASE5 directory. For example, /QIBM/UserData/WebASE/Base/classes.</p></li>
|
|
|
|
<li><p>Grant read, write, and execute authority (*RWX) to the QEJBSVR user profile. You can use the i5/OS Change Authority (CHGAUT) command, for example:</p>
|
|
|
|
<pre>CHGAUT OBJ('/QIBM/UserData/WebASE/ASE5/classes') USER(QEJBSVR) DTAAUT(*RWX) </pre></li>
|
|
|
|
<li><p>Restart the server.</p></li>
|
|
|
|
<li><p>Use the administrative console to delete the default WebSEAL interceptor and add your custom interceptor. Verify that the class name is dot separated and appears in the class path. For instructions on configuring trust association interceptors, see <a href="secctai.htm">Configure a trust association interceptor</a>.</p></li>
|
|
|
|
<li><p>Click <strong>Custom Properties</strong> to add additional properties that are required to initialize the custom interceptor.</p></li>
|
|
|
|
<li><p>Save the configuration.</p></li>
|
|
|
|
<li><p>Stop and restart the application server.</p></li>
|
|
</ol><p></p></li>
|
|
</ol>
|
|
|
|
</body>
|
|
</html>
|