When you develop Session Initiation Protocol (SIP) applications,
you can create a custom trust association interceptor (TAI).
Before you begin
You might want to familiarize yourself 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 an extension of the trust association interceptor model. Refer
to the Developing a custom interceptor for trust associations
section for more details.
You can find the
com.ibm.websphere.security.tai.extension.SIPTrustAssociationInterceptor
interface
in the wasHome/plugins/com.ibm.ws.sip.container.jar file.
The rest of the required SIP interfaces are in the
wasHome/plugins/com.ibm.ws.sip.interface.jar file. The
com.ibm.wsspi.security.tai.TAIResult
class is in the
wasHomedev/was_public.jar file. Make sure that these
JARfiles are available when you compile your custom interceptor.
About this task
TAI can be invoked by a SIP servlet request or a SIP servlet
response. To implement a custom SIP TAI, you need to write your own
Java class.
Procedure
-
Write a Java class that extends the
com.ibm.wsspi.security.tai.extension.BaseTrustAssociationInterceptor
class and
implements the
com.ibm.websphere.security.tai.extension.SIPTrustAssociationInterceptor
interface.
Those classes are defined in the
wasHome/plugins/com.ibm.ws.sip.container_1.0.0.jar file,
where wasHome is the fully qualified path name of the directory in which WebSphere Application Server is installed.
- Declare the following Java methods, which are required by the
SIPTrustAssociationInterceptor
interface:
public int initialize(Properties properties) throws
WebTrustAssociationFailedException;
- This method is invoked before the first message is processed so that the implementation can
allocate any resources that it needs it. For example, it might establish a connection to a database.
The value of the
properties
argument comes from the Custom
Properties set in this step.
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.
public void cleanup();
- This method is invoked when the TAI must free any resources that it holds. For example, it might
close a connection to a database.
public boolean isTargetProtocolInterceptor(SipServletMessage sipMsg) throws
WebTrustAssociationFailedException;
- Your custom TAI uses 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 that
is being processed and a user ID or the unique ID for the user who is trying to authenticate. If
authentication succeeds, the TAIResult
contains the status
HttpServletResponse.SC_OK
and a principal. If authentication fails, the
TAIResult
contains a return code of HttpServletResponse.SC_UNAUTHORIZED
(401)
, SC_FORBIDDEN (403)
, or SC_PROXY_AUTHENTICATION_REQUIRED
(407)
. This code indicates only whether the container accepts a message for further
processing. To challenge an incoming request, the TAI implementation must generate and send s own
SipServletResponse
that contained a challenge. The exception is thrown for internal
TAI errors. Table 1 describes the argument values and resultant
actions for the negotiateValidateandEstablishProtocolTrust
method.
Table 1. Description of negotiateValidateandEstablishProtocolTrust arguments and
actions .
This table provides a description of negotiateValidateandEstablishProtocolTrust arguments and
actions.
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 that contains 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 by 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 is not usable within
the request-mapping process because it finishes before the container invokes the TAI.
For more information about how to create a TAIResult
object to return from the
negotiateValidateandEstablishProtocolTrust
method, see Trust association
interceptor support for subject creation.
The following example shows a bare custom SIP interceptor. You can add your custom implementation
to this code.
import java.util.Properties;
import javax.servlet.sip.SipServletMessage;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipServletResponse;
import com.ibm.websphere.security.WebTrustAssociationFailedException;
import com.ibm.websphere.security.tai.extension.SIPTrustAssociationInterceptor;
import com.ibm.wsspi.security.tai.TAIResult;
import com.ibm.wsspi.security.tai.extension.BaseTrustAssociationInterceptor;
public class mySIPTai extends BaseTrustAssociationInterceptor implements SIPTrustAssociationInterceptor {
public mySIPTai () {}
public int initialize(Properties properties) throws WebTrustAssociationFailedException {
//initialize the implementation. If successful return 0, else return 1.
return 1;
}
public boolean isTargetProtocolInterceptor(SipServletMessage sipMsg) throws WebTrustAssociationFailedException {
// use information from sipMsg to determine if your custom TAI should
// intercept the request
// return true if this is the target interceptor, else return false.
return false;
}
public TAIResult negotiateValidateandEstablishProtocolTrust(SipServletRequest req, SipServletResponse resp)
throws WebTrustAssociationFailedException {
//validate the request and establish trust
TAIResult taiResult = null;
//create and return a TAIResult object, example:
//taiResult = TAIResult.create(HttpServletResponse.SC_OK, userid);
return taiResult;
}
public String getVersion() {
//Return a version specific to your implementation
return "1.0";
}
public String getType() {
//Return a type specific to your implementation
return "my custom SIP TAI";
}
public void cleanup() {
//Cleanup code specific to your implementation
}
}
- Compile the implementation after you implement it.
For example:
/opt/WebSphere/AppServer/java/bin/javac -classpath /opt/WebSphere/AppServer/dev/was_public.jar;/opt/WebSphere/AppServer/dev/JavaEE/j2ee.jar;/opt/WebSphere/AppServer/plugins/com.ibm.ws.sip.container.jar;/opt/WebSphere/AppServer/plugins/com.ibm.ws.sip.interface.jar
- For each server within a cluster, copy the class file to a location in the WebSphere
class path, preferably the wasHome/plugins/ directory.
- Restart all the servers.
- Enable trust association.
- In the administrative console, click .
- Under Authentication, click .
- Make sure that the Enable trust association box is
checked.
- Click Apply.
- Optional: Delete the deprecated interceptor.
- Under Additional properties, click
Interceptors.
- If the
com.ibm.ws.security.web.TAMTrustAssociationInterceptorPlus
interceptor is listed, select it by checking the box.
- Click Delete.
- Add your custom interceptor.
- Click New.
- Enter your interceptor class name.
Verify that the class name is
dot-separated and appears in the class path.
- Optional: Add properties that are required to initialize
the custom interceptor.
These properties are passed to the
initialize(Properties)
method of your interceptor when it extends the
com.ibm.wsspi.security.tai.extension.BaseTrustAssociationInterceptor
class, as
previously described.
- Save the configuration and synchronize it, if applicable.
- Restart the servers for the custom interceptor to take
effect.