Package 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.

See Also:
  • HttpServletRequest
  • HttpServletResponse
  • Subject
  • WebTrustAssociationFailedException

  • Method Summary

    Modifier and Type
    Method
    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.
    String
    getType()
    The trust association interceptor type.
    String
    getVersion()
    Return the version of the trust association implementation.
    int
    initialize(Properties props)
    This method is called to initialize the trust association interceptor.
    boolean
    isTargetInterceptor(jakarta.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(jakarta.servlet.http.HttpServletRequest req, jakarta.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(jakarta.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(jakarta.servlet.http.HttpServletRequest req, jakarta.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.

      Parameters:
      req - Http Servlet Request object
      res - 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.