When you develop Session
Initiation Protocol (SIP) applications,
you can create a custom trust association interceptor (TAI).
Before you begin
You may 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 actually an extension of the trust association interceptor model.
Refer to the Developing
a custom interceptor for trust associations section for more
details.
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.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. Description of negotiateValidateandEstablishProtocolTrust arguments and actions 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
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 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 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. 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 Application Server that the TAI has
completed its negotiation. The response also tells WebSphere Application Server use the information
in the TAIResult to create a user identity.
The created TAIResults
have the meanings shown in Meanings of TAIResults.
Table 2. Meanings of TAIResults. This
table lists the meanings of TAIResults
TAIResult |
Explanation |
public static TAIResult create(int status); |
Indicates a status to 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 WebSphere Application Server and provides the
user ID or the unique ID for this user. WebSphere Application Server creates credentials
by querying the user registry. |
public
static TAIResult create(int status, String
principal, Subject subject); |
Indicates
a status to 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.
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 your 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 that are required to initialize the custom
interceptor. These properties are passed to the initialize(Properties
properties) method of your 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.