![[8.5.5.7 or later]](../ng_v8557.gif)
Developing a custom SIP TAI
When you develop Session Initiation Protocol (SIP) applications, you can create a custom trust association interceptor (TAI).
Before you begin
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 ${wlp.install.dir}/dev/api/ibm/ccom.ibm.websphere.appserver.api.sipServletSecurity.1.0_1.0.10.jar file.
- 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 that it needs. For example, it might establish a connection to a database. WebTrustAssociationFailedException is defined in the ${wlp.install.dir}/lib/com.ibm.websphere.security_1.0.10.jar file. The value of the properties argument comes from the <trustAssociation> configuration.
- public void cleanup();
- This is invoked when the TAI can free any resources that it holds. For example, it could close a connection to a database.
- public boolean isTargetProtocolInterceptor(SipServletMessage sipMsg) throws WebTrustAssociationFailedException;
- Your custom TAI can 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 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 will
contain a return code of HttpServletResponse.SC_UNAUTHORIZED
(401), SC_FORBIDDEN (403),
or SC_PROXY_AUTHENTICATION_REQUIRED (407).
This only indicates whether 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 can be thrown for internal TAI errors. Table 1 describes
the argument values and resultant actions for the negotiateValidateandEstablishProtocolTrust method.The sequence of events is as follows:
Table 1. Description of negotiateValidateandEstablishProtocolTrust arguments and actions. This table provides a description of the 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 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 SIP container maps initial requests to applications by using the rules in each applications deployment descriptor; subsequent messages are mapped based on JSR289 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.
The com.ibm.wsspi.security.tai.TAIResult class, which is defined in the ${wlp.install.dir}/lib/com.ibm.ws.security.authentication.tai_1.0.10.jar file, has three static methods for creating a TAIResult. The TAIResult create methods take an int type as the first parameter. The WebSphere Application Server 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 WebSphere that the TAI has completed its negotiation. The response also tells WebSphere to use the information in the TAIResult to create a user identity.
The created TAIResults have the meanings that are shown in Table 2.
Table 2. Meanings of TAIResults. This table lists the meanings of TAIResults
TAIResult Explanation public static TAIResult create(int status); Indicates a status to the WebSphere Application Server. 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 the WebSphere Application Server and provides the user ID or the unique ID for this user. WebSphere creates credentials by querying the user registry. public static TAIResult create(int status, String principal, Subject subject); Indicates a status to the WebSphere Application Server, 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 you have implemented it to create your own SIP TAI jar file.
- Follow steps 3-4 described in the topic Configuring TAI for Liberty to configure the Liberty server to use the SIP TAI.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=twlp_custom_sip_tai
File name: twlp_custom_sip_tai.html