Level: Intermediate Nataraj Nagaratnam (natarajn@us.ibm.com), Security Architect, IBM
Wilfred Jamison (wjamison@us.ibm.com), Advisory Software Engineer , IBM
Gennaro Cuomo (gcuomo@us.ibm.com), IBM Distinguished Engineer, IBM
01 Jun 2001
Updated 15 Jun 2004 This article describes the problem, the solution achieved by WTA, and illustrates how a third-party security server like WebSEAL (a component of Policy Director), and other similar products can be exploited to perform entry-level authentication and further authorization performed by WebSphere. The objective of the article is to describe a trusted association solution between WebSphere Advanced Edition, Standard Edition, and Web Authentication Servers that fall into the category of RPSS.
As enterprise environments increasingly embrace e-business, many companies are beginning to build their enterprise security infrastructure using IBM WebSphere Application Server. Application Server can co-exist with other Web servers, application servers, and back-end services. In such environments, it is an increasingly common pattern to deploy a third-party security solution provider like Tivoli SecureWay Policy Director (Policy Director). Therefore, a Reverse Proxy Security Server (RPSS) may front end the application server. Alternatively, a third-party security plug-in handles the authentication exit before Application Server or other services in the Web server have an opportunity to handle the request.
Either of these scenarios is referred to as an RPSS. In such an environment, WebSphere should trust these third-party security services that have already authenticated users so that WebSphere does not prompt users for their credentials again. Based on the established trust, WebSphere is expected to handle its own authorization for the servlets as well as controlling access to downstream Enterprise JavaBeans components (EJB) based on the established identity.
The Web Trust Association (WTA) feature in WebSphere enables WebSphere to fit in well in such scenarios. The Trust Association Interceptor Application Program Interface (API) can be implemented to suit any third-party security service and can be deployed in corporate trust environments. This article describes the feature with an example that implements such an interceptor for a hypothetical Proxies-R-Us RPSS.
This article describes the problem, the solution achieved by WTA, and illustrates how a third-party security server like WebSEAL (a component of Policy Director), and other similar products can be exploited to perform entry-level authentication and further authorization performed by WebSphere. The objective of the article is to describe a trusted association solution between WebSphere Advanced Edition, Standard Edition, and Web Authentication Servers that fall into the category of RPSS. Using the trusted association model, WebSphere will trust the RPSS in identifying the user making the request. Once identified, WebSphere will make authorization decisions based on the user identity. The trust in RPSS depends on the trust requirement in the environment deployed and the data provided by the RPSS to WebSphere.
Finally, this article includes a sample implementation of the Web Trust Association Interceptor to illustrate its use. Front-ending authentication servers
WebSphere-RPSS integration problems
In a typical e-business infrastructure, a company's distributed environment consists of Web application servers, Web servers, legacy systems, and one or more RPSS, such as the WebSEAL component of Policy Director. Such RPSSs or security plug-ins registered within Web servers guard the HTTP access requests to the Web servers and Web application servers. While protecting access to the Uniform Resource Identifiers (URIs), these RPSSs perform authentication, coarse-grained authorization, and route the request to the target application server. The credential formed because of the user being authenticated also passes as a part of the request. Unfortunately, most back-end services, including IBM WebSphere, do not understand the format of the credential information passed to them by the RPSS.
The intent of the WTA feature is to have RPSSs exist as the exposed entry points to perform authentication and coarse-grained authorization, while WebSphere enforces further fine-grained access control.
Using the WTA feature:
- RPSS can authenticate WebSphere Web server using server-side Secure Sockets Layer (SSL). It may be able to flow a userid or password in the Authorization header to represent its own identity or perform a mutual SSL with the WebSphere Web server. The strength of the trust relationship between RPSS and WebSphere is based on the criteria of trust association. This level of trust might have to be relaxed based on the environment, but the WebSphere user should be aware of the vulnerabilities in cases where the RPSS is not trusted based on a security technology.
- The end user's credential likely gets sent over in a special format as part of the Hypertext Transfer Protocol (HTTP) headers in the case of RPSS performing the authentication. It may be a special header or a cookie. What data gets passed is implementation specific, and the WTA feature considers this fact and accommodates the idea.
Configuration and assumptions
This WebSphere solution is already available within PTF3 on both WebSphere Standard and Advanced Editions. However, it is supported only under the Lightweight Third Party Authentication (LTPA) service authentication mechanism. Multiple RPSS types can be deployed in the same environment, and different trust relationships may be defined for each of these RPSS types. RPSS cannot be chained; that is, a request is forwarded from the client to an RPSS and then to the WebSphere Web server. WebSphere may be configured such that requests can be submitted without passing through an RPSS.
In this setup, the WebSphere Web server and the first application server that handles the request is in a trusted and isolated zone; that is, they are part of the trusted computing base. The RPSS presents authenticated user identity information as part of the HTTP request that is forwarded to WebSphere. The user information (username or a distinguished name (DN)) presented by RPSS to represent the end user is a valid entry in WebSphere's user registry. To establish trust between WebSphere and RPSS, the latter may be required to present its own credential. The method of exchanging credentials is left for the customer to decide. In other words, the trust policy is defined by the customer and enforced by the implementation of the Web Trust Association Interface (WTAI).
Topologies
This section describes two scenarios that are relevant to the RPSS configurations deployed in WebSphere environments. The first scenario describes the event flow when the security environment does not include an RPSS as an entry point security controller, but only has WebSphere installed. The second scenario introduces RPSS as the entry point into the secure environment such that RPSS performs authentication and passes the resultant information to the back-end server, in this case WebSphere Web server. Scenario 1: WebSphere performs authentication and authorization
Consider a WebSphere default configuration in which the default application server and the default servlet engine host HitCountBean and HitCountServlet respectively. A method invocation on HitCountServlet necessitates a method invocation on HitCountBean. Also, consider that these resources are protected through the administrative console. Assume that security is configured such that the authentication requires a userid and password.
As shown in Figure 1, when a user invokes the HitCountServlet by entering its Web address in a Web browser, the target WebSphere Web server receives the request. It passes on the request to the application server, which determines that the URI representing the resource is a protected URI serviced by WebSphere. The security collaborator in the WebSphere Application Server issues an HTTP 401 challenge back to the browser, through the Web server, requiring the user to enter a userid and password to access the servlet. The security collaborator performs authentication by delegating the task to the security server using the authentication data (userid and password) received from the user. On successful authentication, the security collaborator consults the security application to determine whether the user has permissions necessary to access the URI. If authorization succeeds, the security collaborator sets up a security context with the user's credential information, and passes on the request to the servlet engine to service the request.
Figure 1. User authentication handled by WebSphere Application Server
With this configuration, the HitCountServlet invokes a method on the HitCountBean. A method call from a servlet to an EJB or another servlet is intercepted by the underlying security mechanism for authorization approval. On invoking the increment() method on the HitCountBean, the security collaborator performs security checks based on the security context set up by the servlet engine. If the user is authorized to invoke the method on the HitCountBean, the servlet executes successfully and sends the result to the user's browser. Scenario 2: An RPSS performs authentication and WebSphere performs fine-grained authorization
Consider a WebSphere default configuration in which the default application server and the default servlet engine host HitCountBean and HitCountServlet respectively. A method invocation on HitCountServlet initiates a method invocation on HitCountBean. As shown in Figure 2, the URI of the servlet is protected by both WebSphere and the RPSS, whereas the EJB is protected only by WebSphere. Due to this configuration, the initial authentication is performed by RPSS, and the user's credential is added to the request headers and forwarded to WebSphere. WebSphere uses the identity information set up by the RPSS in the request header to perform credential mapping and further downstream authorization.
Figure 2. User authentication handled by an RPSS
When a user invokes the HitCountServlet by entering its Web address in a Web browser, the target RPSS server receives the request. It consults its configuration database and determines that the requested Web address is protected and hence authenticates the user. It either uses the client certificate passed in by the user, or the userid or password provided by the user to authenticate the user. After a successful authentication, it consults its policy database to determine if the user is allowed to access the requested URI resource.
Next, the RPSS server attaches some information about the authenticated user to the HTTP request (for example, sets a header by name IV_USER) and forwards the request to WebSphere. Such a credential should contain a valid username in the WebSphere user registry. When WebSphere receives the request, the security collaborator in the WebSphere Application Server is configured in such a way that it knows that an RPSS authentication service front-ends WebSphere Web server. Based on the trust relationship with the RPSS, the WebSphere Application Server retrieves the user information present in the HTTP headers. On successful validation of the user, the security collaborator consults the security application to determine whether the user has the permissions necessary to access the URI. If the authorization succeeds, the security collaborator sets up a security context with the user's credential information and passes on the request to the servlet engine to service the request.
As illustrated in the above two scenarios, a user request can be protected in WebSphere in addition to being protected in an RPSS. Using the WTA feature, security context can be established based on the trust in WTA, and downstream requests to EJBs can be protected by WebSphere as if the RPSS never existed.
Web trust association interceptor
Trust association is specific to the characteristics of the RPSS. Therefore, for every type of RPSS, a trust association type is associated and an implementation of the interceptor is required to handle the specific details. The Web Trust Association Interceptor API is designed to address these requirements. TrustAssociationInterceptor interface
An interceptor must implement com.ibm.websphere.security.TrustAssociationInterceptor interface. Based on the trust model and the values available in the HTTP request stream, it is the responsibility of the interceptor to validate the request stream. For example, the WebSEAL 3.6 interceptor authenticates the WebSEAL server's userid and password from the HTTP stream. On a successful trust validation, the WebSphere runtime calls the getAuthenticatedUserName method. This method retrieves the username from the HTTP stream. In the case of WebSEAL 3.6 interceptor, this method retrieves the value associated with the IV_USER header.
The username returned by the getAuthenticatedUserName method call can either be:
- A username that can be mapped to a DN based on WebSphere's Lightweight Directory Access Protocol (LDAP) filter configuration for the installed LDAP directory type.
- A DN in the WebSphere's LDAP user registry.
WebSphere security runtime maps the username to a valid LTPA credential that the WebSphere system can recognize and use for authorization purposes for the downstream requests. Properties
WebSphere Trust Association properties are defined in the trustedservers.properties file, which must be placed in WebSphere's Java CLASSPATH. The file contains entries for interceptor implementations indexed by the type of RPSS. There are three major properties in this file:
com.ibm.websphere.security.trustAssociation.enabled
com.ibm.websphere.security.trustAssociation.type
com.ibm.websphere.security.trustassociation.<type<.interceptor
|
The property com.ibm.websphere.security.trustAssociation.enabled specifies whether WebSphere recognizes the trust association mode and ignores any challenge type specified through configuration. If this property value is set to be true, then the types of RPSS installed in the environment with which WebSphere has to interoperate is specified by the com.ibm.websphere.security.trustAssociation.types property.
Following is an example of such a setting:
com.ibm.websphere.security.trustAssociation.enabled=true
com.ibm.websphere.security.trustassociation.types=proxies_r_us
|
For every type of trust association interceptors, there needs to be an entry that specifies the name of the interceptor implementation class. This is specified by the com.ibm.websphere.security.trustassociation.<type>.interceptor property. For example,
com.ibm.websphere.security.trustassociation.proxiesrus.interceptor=
com.proxiesrus.tai.Proxies_R_USInterceptor
|
Sample implementation of Proxies-R-Us interceptor
Listing 1 shows a simple example of an interceptor code for a hypothetical Proxies-R-Us RPSS. The proxy is expected to be placed on a specific host and listening to a preassigned port. This information is used to determine if the interceptor should handle the request or whether the request came through a different proxy (or directly to the Web server). This is done in the isTargetInterceptor method.
Listing 1. Determining the type of interceptor to handle the request
public boolean isTargetInterceptor (HttpServletRequest req)
throws WebTrustAssociationException
{
// check if request must come from a specified location
if (reqviahost == null && reqviaport == null)
return true
Enumeration e = req.getHeaderNames();
while ( e.hasMoreElements() )
{
String name = (String)e.nextElement();
/* Now, check for "RoutedThrough" header */
if (name.equalsIgnoreCase("RoutedThrough")) {
// retrieve RoutedThrough information
String via = req.getHeader (name);
// does it have a value ?
if (via != null && via.trim().length() > 0 )
{
// Remove the prefixing "HTTP/1.0" string
int i=via.indexOf (' ');
if (i != -1) {
via = via.substring (i+1);
// Now, separate hostname and port
i=via.indexOf(':');
String viahost = via.substring (0, i);
String viaport = via.substring (i+1);
if ( reqviahost == null ||
(viahost != null && viahost.equalsIgnoreCase
(reqviahost)))
if ( reqviaport == null || (viaport != null &&
viaport.equals(reqviaport)))
return true;
return false;
}
}
}
}
// Unable to get source path from request header 'via'
throw new WebTrustAssociationException ();
|
To establish the trust, this interceptor becomes the target interceptor if there is a header present called RoutedThrough that contains some trusted values. This is a sample only. Such trust should be based on a secure protocol such as using mutual SSL authentication or validating a kerberos token of the RPSS. The sample code shows that the required source host and source port are stored in reqviahost and reqviaport respectively. The values can be initialized from a configuration file. Therefore, if the request was sent by a server from reqviahost that listens in port reqviaport, it must be from a Proxies-R-Us server. Check for this by inspecting the RoutedThrough header in the HTTP request.
To establish trust between the Proxies-R-Us server and its interceptor, Proxies-R-Us-Interceptor, the former places a userid and password in the Basic Authorization header of every HTTP requests it sends to WebSphere. Next, the interceptor examines the userid and password to compare them with the expected username and password pair. In a different scenario where mutual SSL is established between WebSphere and the RPSS, the interceptor can either rely on the trust provided by the SSL handshake performed by the Web server (and hence not do anything in this method), or investigate the client certificate of the proxy server to determine the RPSS.
In Listing 2, the required username and password are stored in reqUsername and reqPassword respectively. They can be initialized from a configuration file.
Listing 2. Verifying the level of excepted trust between RPSS and Application Server
public void validateEstablishedTrust (HttpServletRequest req)
throws WebTrustAssociationFailedException
{
// no required user and password then we simply allow
if (reqUsername==null && reqPassword==null)
return;
// We need to check the authorization header to make sure that
// it uses Basic Authentication. If not, simply fail everything.
String hdrValue = req.getHeader(WebCollaborator.pnAuthorization);
if (hdrValue == null || !hdrValue.startsWith("Basic ")) {
throw new WebTrustAssociationFailedException
("Basic Auth is expected in Trust Association mode.");
}
// Now get the username and password from the header.
hdrValue = new String ( (new Base64()).decode(
hdrValue.substring(6).getBytes()) );
int idx = hdrValue.indexOf(':');
if (idx < 0) {
throw new WebTrustAssociationFailedException (
"Basic Auth username/password field is missing.");
}
String username = hdrValue.substring(0,idx);
String password = hdrValue.substring(idx+1);
// Now, check the username and password
if ( reqUsername==null || (username.equalsIgnoreCase (reqUsername)) )
if (reqPassword==null || (password.equalsIgnoreCase (reqPassword)))
return;
throw new WebTrustAssociationFailedException("Basic Authentication
failed.");
}
|
After successfully establishing the trust, the interceptor needs to obtain the user information that is passed to WebSphere by the RPSS. The information may be as simple as an HTTP header containing the username, or some form of an encrypted token that the interceptor should decrypt and deduce the username from that token. In Listing 3, the username of the original client that requested the resource also is placed in the HTTP request through a header called UserClient. This is extracted and returned in the getAuthenticatedUserName method.
Listing 3. Retrieve the identity of the user making the request
public String getAuthenticatedUsername (HttpServletRequest req)
throws WebTrustAssociationUserException
{
String username=null;
Enumeration e = req.getHeaderNames();
while ( e.hasMoreElements() )
{
String name = (String)e.nextElement();
// Now, is this name equal to UserClient ?
if ( name.equalsIgnoreCase ("UserClient") ) {
// Yes, we found it! Get the value.
username = req.getHeader(name);
if (username != null && username.trim().length() > 0)
return username;
}
}
// If we reach this point, we know there was no username retrieved
throw new WebTrustAssociationUserException
("No user was found in request header.");
}
|
The Proxies_R_UsInterceptor.java sample file provides a complete interceptor implementation. There are classes (such as the Base64.class) that it depends on, that are not given as part of the example.
Notice that the constructor invokes an init method that initializes the values for the required source hostname, source port, username, and password. These values are read from a configuration file named proxies_r_us.properties. You can compile and try out this source code. To do so, include the publicly available org.apache.catalina.util.Base64 class from the Apache Tomcat source code. When deploying the interceptor with WebSphere, make sure that com/proxiesrus/tai/Proxies_R_UsInterceptor.class and org/apache/catalina/util/Base64.class can be located by the class loader through the CLASSPATH.
Create two property files as well and store them in the $WAS_HOME/properties directory where WAS_HOME is the root directory of the WebSphere installation. The first file, trustedservers.properties, contains the following:
com.ibm.websphere.security.trustassociation.enabled=true
com.ibm.websphere.security.trustassociation.types=proxies_r_us
Com.ibm.websphere.security.trustassociation.proxies_r_us.interceptor=
com.proxiesrus.tai.Proxies_R_UsInterceptor
com.ibm.websphere.security.trustassociation.proxies_r_us.config=
proxies_r_us
|
while the second file, proxies_r_us.properties, contains the following:
com.proxiesrus.tai.sourcehost=bach
com.proxiesrus.tai.sourceport=7646
com.proxiesrus.tai.username=administrator
com.proxiesrus.tai.password=myPassword
|
Note that the reader must change the values for these properties appropriately. For com.proxiesrus.tai.sourcehost, use the fully qualified host name if the shortname does not work. Make sure to enable WebSphere security using LTPA as the authentication mechanism.
To be able to test the interceptor, the ProxiesRUsServer.java sample file simulates the Proxies_R_Us RPSS. To compile and run the program, ensure that the Apache class org.apache.catalina.util.Base64 can be loaded from the CLASSPATH. The sample code is a simple Java program that asks the user for the following information:
-
Username. The username of the end user
-
Password. The password of the username
-
Web server host. The hostname of the host where the WebSphere Web server is located
-
Web server port. The port to which the Web server is listening, typically equal to 80
-
Request URI. The URI of the resource being requested, for example, /servlet/hello
-
Trusted Username. The username that is trusted by the Proxies_R_UsInterceptor; this is equivalent to the username specified in proxies_r_us.properties
-
Trusted Password. The password of the trusted username; this is equivalent to the password specified in proxies_r_us.properties
After providing this information, WebSphere authorizes access to the resource depending on the result of validating the Trusted Username and Trusted Password and the permissions given to username. Thus, username must be a valid user in the WebSphere registry and must have the right access permissions to the requested URI. The sample code receives a response from the Web server and prints it on the screen.
Note also that the values for trusted_username and trusted_password must be changed accordingly. Multiple RPSS instances
It is possible to have several RPSSs to front-end WebSphere. They can even be a combination of different types of RPSSs. For example, consider a configuration where WebSEAL co-exists with a hypothetical Proxies-R-Us RPSS. WebSphere security runtime finds the right interceptor to handle a given request by interrogating the active interceptors using their isTargetInterceptor method. In the current design, only the first interceptor to return a positive response is going to handle the request. The order in which the interceptors are going to be interrogated is the same order that they were specified in the properties file.
As shown in Figure 3, the request that was forwarded to WebSphere was originally routed through WebSEAL. Therefore, the Proxies-R-Us interceptor does not handle the request, but the WebSEAL interceptor does.
Figure 3. Multiple RPSS can coexist
Single Sign-On
WebSphere Single Sign-On (SSO) works in trust association scenarios as well. There are configurations where the RPSS handles SSO itself. Consider that Proxies-R-Us has such a functionality. If the environment is configured such that there is only one Proxies-R-Us server and several junctions to different WebSphere Web servers such as on the left side of Figure 4, SSO itself is taken care of by Proxies-R-Us. Even for a setup consisting of several Proxies-R-Us servers where each has an exclusive junction to a WebSphere Web server, as shown on the right side of Figure 4, SSO works the same.
Figure 4. Trust Association in a clustered environment
One configuration item to remember, however, is that WebSphere should be enabled to handle trust association in this scenario. If trust association is not enabled, Proxies-R-Us still authenticates the user. Because there is no interceptor involved on WebSphere's side, WebSphere applies whatever challenge type is configured for the resource requested. If the challenge type is basic, WebSphere uses the userid and password present in the header (if any) or sends a 401 challenge back to the user through the proxy server. Thus, any user information set by the RPSS is ignored.
Conclusion
The Trust Association interceptor framework allows third-party RPSSs or security plug-ins to perform front-end authentication and allows WebSphere security runtime to perform further authorization. The expected configuration delegates authentication responsibilities to the proxy servers while WebSphere applies its authorization policies. The mechanism for trust validation depends on the specific implementation of the Trust Association interceptor for each particular proxy server. In this article, we presented the key concepts of Trust Association as they apply within the context of IBM WebSphere 3.5. For illustration, this article provides a sample way of writing Trust Association interceptors using a hypothetical reverse proxy Proxies-R-Us. The same mechanism explained in this article can be used to implement interceptors for other types of third-party RPSSs or security plug-ins.
Download | Name | Size | Download method |
|---|
| i-tpss.zip | | HTTP |
Resources
About the authors  | | | Nataraj Nagaratnam is an IBM WebSphere security architect. He received his PhD from Syracuse University, and his thesis addresses Secure Delegation in Distributed Object Environments. He has authored and edited books on Java Networking and JavaBeans and has published his research work in numerous journals and conferences. You can contact him at natarajn@us.ibm.com. |
| 
| | Wilfred Jamison is an advisory software engineer for IBM WebSphere Security and Performance. He received his PhD from Syracuse University where he worked on coordination of distributed software agents. He designed and implemented TRUCE, a Java-based coordination scripting language. He has also done work on Socks, IPSec, and Policy Director with IBM Firewall. You can contact him at wjamison@us.ibm.com. |
| | | Gennaro Cuomo is an IBM Distinguished Engineer and leads the WebSphere Performance and Technology team. You can contact him at gcuomo@us.ibm.com.
|
Rate this page
| 
