com.ibm.wsspi.security.tai

Interface TrustAssociationInterceptor

public interface TrustAssociationInterceptor

Trust Association interface (com.ibm.wsspi.security.tai.TrustAssociationInterceptor) is a service provider API that enables the integration of third party security service (for example, a reverse Proxy, etc) with WebSphere Application Server.

The idea is during processing the Web request, WebSphere Application Server calls out and pass the HttpServletRequest and HttpServletResponse to the trust association interceptors. The trust association interceptors are considered to be trusted by WebSphere Application Server. The trust association interceptors can inspect the HttpServletRequest to see if it contains security attributes (authentication or authorization attributes) from the third party security service.

The following is the high level flow:

1. The isTargetInterceptor method of the trust association interceptor is called with HttpServletRequest as parameter. The trust association interceptor inspects to see it can process the request based on information in the HttpServletRequest agreed upon with the third party security service. The implementation should return true if it is the appropriate trust association interceptor, else false should be returned.
2. If appropriate trust association interceptor is selected, the method negotiateValidateandEstablishTrust is called with HttpServletRequest and HttpServletResponse.
   • If the interceptor finds that the request does not contains the expected authentication data, it can write the protocol specific challenge information in the HttpServletResponse and return status code that is not equal to HttpServletResponse.SC_OK in the TAIResult. WebSphere Application Server security runtime will stop processing the request and send a status code back to the initiator.
   • If the interceptor finds the agreed upon security information in the HttpServletRequest, then it should validate and establish the trust based on the agreed upon protocol with the third party security services, like for example, validate the signature of the security information, decrypt the security information, etc. Once the trust is validated and established, then the trust association interceptor may create a JAAS Subject (optional) populated with the security information (please see security attribute propagation documentation for details on the format) and it should create a TAIResult with the JAAS Subject, the authenticated principal and the status code as HttpServletResponse.SC_OK. If for some reason the validation fail or trust can not be established, the a WebTrustAssociationFailedException should be thrown.
3. The WebSphere Application Server security runtime then can use the security information in the JAAS Subject (if JAAS Subject is present) and the authenticated principal in the TAIResult to create WebSphere Application Server security credential and proceeds with its normal processing.

Version:

5.1.1

See Also:

HttpServletRequest, HttpServletResponse, Subject, WebTrustAssociationFailedException

Method Summary

Methods

Modifier and Type	Method and Description
void	cleanup() This is called during stopping the WebSphere Application Server process, this provides an opportunity for trust association interceptor to perform any necessary clean up.
java.lang.String	getType() The trust association interceptor type.
java.lang.String	getVersion() Return the version of the trust association implementation.
int	initialize(java.util.Properties props) This method is called to initialize the trust association interceptor.
boolean	isTargetInterceptor(javax.servlet.http.HttpServletRequest req) Every interceptor should know which HTTP requests originate from the third party server that it is supposed to work with.
TAIResult	negotiateValidateandEstablishTrust(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) This method is used to determine whether trust association can be established between WebSphere Application Server and the third party security service.

Method Detail

isTargetInterceptor

boolean isTargetInterceptor(javax.servlet.http.HttpServletRequest req)
                            throws WebTrustAssociationException

Every interceptor should know which HTTP requests originate from the third party server that it is supposed to work with.

Given an HTTP request, this method must be used to determine whether or not this interceptor is designed to process the request, in behalf of the trusted server it is designed to interoperate with.

The determination algorithm depends on the specific implementation. But it should be able to unequivocally give either a positive or negative response. If for any reason the implementation encounters a situation where it is not able to give a definite response (such as, not enough information, indeterminate state, remote exception, etc), then the method should throw a WebTrustAssociationException. The caller is left to decide on what to do if an exception is received.

Parameters:

req - The HTTP Request object (HttpServletRequest)

Returns:

If this is the appropriate interceptor to process the request, true should be returned.

Throws:

WebTrustAssociationException - Should be thrown if any reason the implementation encounters a situation where it is not able to give a definite response (such as, not enough information, indeterminate state, remote exception, etc).

See Also:

HttpServletRequest

negotiateValidateandEstablishTrust

TAIResult negotiateValidateandEstablishTrust(javax.servlet.http.HttpServletRequest req,
                                           javax.servlet.http.HttpServletResponse res)
                                             throws WebTrustAssociationFailedException

This method is used to determine whether trust association can be established between WebSphere Application Server and the third party security service. In most situations, this involves authenticating the server. All the required information to be able to do this should be available in the HTTP request.

If the third party server failed the validation, or is unable to provide the required information, a WebTrustAssociationFailedException must be thrown.

However, if the interceptor finds that the request does not contains the expected authentication data, it can write the protocol specific challenge information in the response and return TAIResult with status code that is not equal to HttpServletResponse.SC_OK. The WebSphere Application Server security runtime will stop processing the request and send a status code back to the initiator. If the validation is successful and trust is established, the a TAIResult is returned with HttpServletResponse.SC_OK code, the authenticated principal and optionally with a JAAS Subject that contains security information from the third party security services (please refer to security attribute propagation documentation for details on the format). The WebSphere Application Server security runtime will proceed to get the authenticated user from TAIResult.getAuthenticationPrincipal and the security information from the JAAS Subject (if present) to create the necessary credentials and proceeds with its normal processing.

Parameters:

req - Http Servlet Request object

res - Http Servlet Response Object

Returns:

TAIResult, contains the outcome of the negotiation, validation and establishing trust.

Throws:

WebTrustAssociationFailedException - If the third party server failed the validation, or is unable to provide the required information, a WebTrustAssociationFailedException must be thrown.

See Also:

Subject, HttpServletRequest, HttpServletResponse, TAIResult

initialize

int initialize(java.util.Properties props)
               throws WebTrustAssociationFailedException

This method is called to initialize the trust association interceptor. This needs to be implemented by all the trust association interceptor implementations when properties are defined in trust association properties.

The return status is now checked before using the trust association interceptor implementation. A return of 0 is considered SUCCESS and anything else a FAILURE. If your previous implementation of the TAI returns a different error status you can either change your implementation to match the expectations or do one of the following:

1. Add the property com.ibm.websphere.security.trustassociation.initStatus in the Trust Association Interceptor custom properties and set it to the value that indicates SUCCESS in your implementation. All other values imply failure. In case of failure, the corresponding TAI implementation will not be used.
2. Add the property com.ibm.websphere.security.trustassociation.ignoreInitStatus in the Trust Association Interceptor custom properties and set it to true to indicate to WebSphere to ignore the status of this method. In this case WebSphere will not check the return status from this method just like in the earlier versions.

Parameters:

props -

Returns:

int - By default, 0 indicates success and anything else a failure. However, to be comparable with earlier versions, the return type can be set to any value to indicate success by setting the com.ibm.websphere.security.trustassociation.initStatus property to that value or one can set the property com.ibm.websphere.security.trustassociation.ignoreInitStatus to inform WebSphere Application Server to ignore the return status.

Throws:

WebTrustAssociationFailedException - Thrown if unrecoverable error is encounter during initialization.

getVersion

java.lang.String getVersion()

Return the version of the trust association implementation.

Returns:

The version of the trust association interceptor.

getType

java.lang.String getType()

The trust association interceptor type.

Returns:

The trust association interceptor type

cleanup

void cleanup()

This is called during stopping the WebSphere Application Server process, this provides an opportunity for trust association interceptor to perform any necessary clean up. If there is no clean up required, then this method can be no-op.