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:
-
The
isTargetInterceptor
method of the trust association interceptor is called withHttpServletRequest
as parameter. The trust association interceptor inspects to see it can process the request based on information in theHttpServletRequest
agreed upon with the third party security service. The implementation should returntrue
if it is the appropriate trust association interceptor, elsefalse
should be returned. -
If appropriate trust association interceptor is selected, the method
negotiateValidateandEstablishTrust
is called withHttpServletRequest
andHttpServletResponse
.-
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 toHttpServletResponse.SC_OK
in theTAIResult
. 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 aTAIResult
with the JAAS Subject, the authenticated principal and the status code asHttpServletResponse.SC_OK
. If for some reason the validation fail or trust can not be established, the aWebTrustAssociationFailedException
should be thrown.
-
If the interceptor finds that the request does not contains the expected authentication data, it can write
the protocol specific challenge information in the
-
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.
- See Also:
-
HttpServletRequest
HttpServletResponse
Subject
WebTrustAssociationFailedException
-
Method Summary
Modifier and TypeMethodDescriptionvoid
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.getType()
The trust association interceptor type.Return the version of the trust association implementation.int
initialize
(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.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 Details
-
isTargetInterceptor
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.
- Parameters:
req
- The HTTP Request object (HttpServletRequest
)- Returns:
- If this is the appropriate interceptor to process the request,
true
should be returned. - Throws:
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).- See Also:
-
HttpServletRequest
-
negotiateValidateandEstablishTrust
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 toHttpServletResponse.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 aTAIResult
is returned withHttpServletResponse.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 fromTAIResult.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 objectres
- Http Servlet Response Object- Returns:
- TAIResult, contains the outcome of the negotiation, validation and establishing trust.
- Throws:
com.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.- See Also:
-
initialize
int initialize(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.
A return of 0 is considered SUCCESS and anything else a FAILURE. The WebSphere Application Server security runtime will call the trust association interceptor regardless of initialize status code.
- Parameters:
properties
- Properties are defined in trust association properties.- Returns:
- int - By default, 0 indicates success and anything else a failure.
- Throws:
com.ibm.websphere.security.WebTrustAssociationFailedException
- Thrown if unrecoverable error is encounter during initialization.
-
getVersion
String getVersion()Return the version of the trust association implementation.
- Returns:
- The version of the trust association interceptor.
-
getType
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.
-