SIP: Develop a custom trust association interceptor

SIP: Develop a custom trust association interceptor

When we develop SIP applications, we can create a custom trust association interceptor (TAI).

You may want to familiarize ourself with the general TAI information contained in the Trust Associations documentation. Developing a SIP TAI is similar to developing any other custom interceptors used in trust associations. In fact, a custom TAI for a SIP application is actually an extension of the trust association interceptor model. Refer to the Develop a custom interceptor for trust associations section for more details.

TAI can be invoked by a SIP servlet request or a SIP servlet response. To implement a custom SIP TAI, we need to write our own Java class.

Tasks

Write a Java class that extends the com.ibm.wsspi.security.tai.BaseTrustAssociationInterceptor class and implements the com.ibm.websphere.security.tai.SIPTrustAssociationInterceptor interface. Those classes are defined in the WASProductDir/plugins/com.ibm.ws.sip.container_1.0.0.jar file, where WASProductDir is the fully qualified path name of the directory in which WebSphere Application Server is installed.
Declare the following Java methods:

public int initialize(Properties properties) throws WebTrustAssociationFailedException;

This is invoked before the first message is processed so that the implementation can allocate any resources it needs. For example, it could establish a connection to a database. WebTrustAssociationFailedException is defined in the WASProductDir/plugins/com.ibm.ws.runtime_1.0.0.jar file. The value of the properties argument comes from the Custom Properties set in this step.

public void cleanup();

This is invoked when the TAI should free any resources it holds. For example, it could close a connection to a database.

public boolean isTargetProtocolInterceptor(SipServletMessage sipMsg) throws WebTrustAssociationFailedException;

Your custom TAI should use this method to handle the sipMsg message. If the method returns false, WebSphere ignores your TAI for sipMsg.

public TAIResult negotiateValidateandEstablishProtocolTrust (SipServletRequest req, SipServletResponse resp) throws WebTrustAssociationFailedException;

This method returns a TAIResult that indicates the status of the message being processed and a user ID or the unique ID for the user who is trying to authenticate. If authentication succeeds, the TAIResult should contain the status HttpServletResponse.SC_OK and a principal. If authentication fails, the TAIResult should contain a return code of HttpServletResponse.SC_UNAUTHORIZED (401), SC_FORBIDDEN (403), or SC_PROXY_AUTHENTICATION_REQUIRED (407). This only indicates whether or not the container should accept a message for further processing. To challenge an incoming request, the TAI implementation must generate and send its own SipServletResponse containing a challenge. The exception should be thrown for internal TAI errors. Table 1 describes the argument values and resultant actions for the negotiateValidateandEstablishProtocolTrust method.

Argument or action For a SIP request For a SIP response
Value of req argument The incoming request Null
Value of resp argument Null The incoming response
Action for valid response credentials Return TAIResult.status containing SC_OK and a user ID or unique ID Return TAIResult.status containing SC_OK and a user ID or unique ID
Action for incorrect response credentials Return the TAIResult with the 4xx status Return the TAIResult with the 4xx status
The sequence of events is as follows:

The SIP container maps initial requests to applications using the rules in each applications deployment descriptor; subsequent messages are mapped based on JSR 116 mechanisms.
If any of the applications require security, the SIP container invokes any defined TAI implementations for the message.
If the message passes security, the container invokes the corresponding applications.
Your TAI implementation can modify a SIP message, but the modified message will not be usable within the request mapping process, because it finishes before the container invokes the TAI.
The com.ibm.wsspi.security.tai.TAIResult class, defined in the WASProductDir/plugins/com.ibm.ws.runtime_1.0.0.jar file, has three static methods for creating a TAIResult. The TAIResult create methods take an int type as the first parameter. WAS expects the result to be a valid HTTP request return code and is interpreted as follows:

If the value is HttpServletResponse.SC_OK, this response tells WAS that the TAI has completed its negotiation. The response also tells WAS use the information in the TAIResult to create a user identity.

The created TAIResults have the meanings shown in Table 2.

TAIResult Explanation
public static TAIResult create(int status); Indicates a status to WAS. The status should not be SC_OK because the identity information is provided.
public static TAIResult create(int status, String principal); Indicates a status to WAS and provides the user ID or the unique ID for this user. WAS creates credentials by querying the user registry.
public static TAIResult create(int status, String principal, Subject subject); Indicates a status to WAS, the user ID or the unique ID for the user, and a custom Subject. If the Subject contains a Hashtable, the principal is ignored. The contents of the Subject becomes part of the eventual user Subject.

public String getVersion();

This method returns the version number of the current TAI implementation.

public String getType();

This method's return value is implementation-dependent.

Compile the implementation after we have implemented it. For example: /opt/WebSphere/AppServer/java/bin/javac -classpath /opt/WebSphere/AppServer/plugins/com.ibm.ws.runtime_1.0.0.jar;/opt/WebSphere/AppServer/dev/JavaEE/j2ee.jar;/opt/WebSphere/AppServer/plugins/com.ibm.ws.sip.container_1.0.0.jar myTAIImpl.java

For each server within a cluster, copy the class file to a location in the WebSphere class path (preferably the WASProductDir/plugin/ directory).
Restart all the servers.

Delete the default WebSEAL interceptor in the administrative console and click New to add our custom interceptor. Verify that the class name is dot-separated and appears in the class path.
Click the Custom Properties link to add additional properties required to initialize the custom interceptor. These properties are passed to the initialize(Properties properties) method of our implementation when it extends the com.ibm.websphere.security.WebSphereBaseTrustAssociationInterceptor as described in the previous step.
Save and synchronize (if applicable) the configuration.
Restart the servers for the custom interceptor to take effect.

Related:

Trust associations
Browse all SIP topics
Developing SIP applications
Trust association interceptor support for Subject creation
Trust association interceptor settings

Argument or action	For a SIP request	For a SIP response
Value of req argument	The incoming request	Null
Value of resp argument	Null	The incoming response
Action for valid response credentials	Return TAIResult.status containing SC_OK and a user ID or unique ID	Return TAIResult.status containing SC_OK and a user ID or unique ID
Action for incorrect response credentials	Return the TAIResult with the 4xx status	Return the TAIResult with the 4xx status

TAIResult	Explanation
public static TAIResult create(int status);	Indicates a status to WAS. The status should not be SC_OK because the identity information is provided.
public static TAIResult create(int status, String principal);	Indicates a status to WAS and provides the user ID or the unique ID for this user. WAS creates credentials by querying the user registry.
public static TAIResult create(int status, String principal, Subject subject);	Indicates a status to WAS, the user ID or the unique ID for the user, and a custom Subject. If the Subject contains a Hashtable, the principal is ignored. The contents of the Subject becomes part of the eventual user Subject.