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:
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.
negotiateValidateandEstablishTrust
is called with HttpServletRequest
and HttpServletResponse
.
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.
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.
TAIResult
to create WebSphere Application
Server security credential and proceeds with its normal processing.
HttpServletRequest
,
HttpServletResponse
,
Subject
,
WebTrustAssociationFailedException
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.
|
boolean isTargetInterceptor(javax.servlet.http.HttpServletRequest req) throws com.ibm.websphere.security.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.
req
- The HTTP Request object (HttpServletRequest
)true
should be returned.com.ibm.websphere.security.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).HttpServletRequest
TAIResult negotiateValidateandEstablishTrust(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) throws com.ibm.websphere.security.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.
req
- Http Servlet Request objectres
- Http Servlet Response Objectcom.ibm.websphere.security.WebTrustAssociationFailedException
- If the third party server failed the validation, or is unable to provide the required
information, a WebTrustAssociationFailedException must be thrown.Subject
,
HttpServletRequest
,
HttpServletResponse
,
TAIResult
int initialize(java.util.Properties props) throws com.ibm.websphere.security.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:
properties
- Properties are defined in trust association properties.com.ibm.websphere.security.WebTrustAssociationFailedException
- Thrown if unrecoverable error is encounter during initialization.java.lang.String getVersion()
Return the version of the trust association implementation.
java.lang.String getType()
The trust association interceptor type.
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.