| Oracle® Communication and Mobility Server Developer's Guide Release 10.1.3 Part Number E10293-02 |
|
|
View PDF |
| Oracle® Communication and Mobility Server Developer's Guide Release 10.1.3 Part Number E10293-02 |
|
|
View PDF |
This chapter describes advanced topics related to SIP servlets through the following sections:
Because JSR 116 does not state how to set the address for a SIP application, OCMS extends the specification by including a parameter called appId, (application ID) which is located either in the URI of the top-most ROUTE header (Example 3-1), or in the REQUEST URI (Example 3-2) of request messages. The OCMS SIP servlet container checks both of these fields for this parameter, one that ensures that the appropriate application is invoked in response to incoming INVITE, MESSAGE, PUBLISH, REGISTER, and SUBSCRIBE requests.
When the OCMS SIP servlet container receives incoming requests that do not contain the appId parameter, it invokes the Application Router to insert the application routing information in the request's ROUTE header.
Note:
In general, any requests generated by a SIP client other than Oracle Communicator will not contain the
appId parameter in either the ROUTE or REQUEST URI headers.How the OCMS SIP Servlet Container Identifies the appId Parameter
The OCMS SIP servlet container interprets the value defined for the appId parameter as the name of the application to invoke for an incoming request. This value can be defined as either the full application name, or the application alias that is set using the ApplicationAliases attribute of the SipServletContainer MBean (described in Oracle Communication and Mobility Server Administrator's Guide). For example, if the OCMS SIP servlet container receives a request that includes the appId parameter, the container searches for the value set for the parameter, such as presence in Example 3-1. If the container cannot find an application named presence, it returns a 403 Response (Forbidden). However, if the container locates the application defined by the appId parameter, it requests this application to process the request using the match method described in "Servlet Mapping" in Chapter 2. If the application does not have a servlet with a matching rule, then the match method returns null and the container replies with a 403 Response.
If the request does not contain a ROUTE header, then the container checks appId included in the REQUEST URI.
Example 3-1, illustrates a ROUTE header present in the request. If the OCMS SIP servlet container has been configured to acknowledge the IP address of 192.168.0.100 as its address, it then uses the appId in the ROUTE header and invokes the application called presence.
Example 3-1 The appId Parameter in the Route Header of an Incoming Request
SUBSCRIBE sip:bob@example.com To: . From: . Route: <sip:192.168.0.100:5060;appId=presence>
Example 3-2 illustrates the appId present in the REQUEST URI. As in Example 3-1, if the OCMS SIP servlet container uses the appId in the REQUEST URI header and invokes the application presence if it has been configured to acknowledge 192.168.0.100 as its IP address.
Example 3-2 The appId Parameter in the Request URI of an Incoming Request
SUBSCRIBE sip:bob@example.com;appId=presence To: . From: . Route: <sip:192.168.0.100:5060>
In some instances, an OCMS SIP servlet container may receive requests that are intended for other IP addresses if the outbound proxy for a SIP client is not a pre-loaded route, but rather a connection to an outbound proxy through which it sends requests. An OCMS SIP servlet container can only consider the appIds contained in requests that are intended for it; even if the container hosts an application that matches the one designated by the appId parameter, it cannot honor the request, as the requested application resides at another IP address and the user requesting the application may not belong to the system.
The appId parameter is configured as part of the SipUriList attribute of the Application Router MBean (ocmsrouteloaderear, illustrated in Figure 3-1). Using this attribute, you set the behavior of the OCMS SIP servlet container in response incoming INVITE, MESSAGE, PUBLISH, REGISTER, and SUBSCRIBE requests by setting the application routing sequence.
Figure 3-1 Setting the Application Routing for an INVITE Request
The SipUriList attribute is comprised of a comma-separated list of URIs, transport methods, and appIds of applications that the Application Router inserts in the ROUTE header of an incoming request.
The default list, which routes requests to the Proxy Registrar, is defined as
sip:<SIP Container IP Address>:<SIP port>;transport=TCP;lr;appId=proxyregistrar
For example:
sip:144.25.174.189:5060;transport=TCP;lr;appId=proxyregistrar
Request routing is set according to the order of the applications listed in this attribute. For example, to call an application called dialin as the first destination for an INVITE request, insert the information for dialin as the first item on the list as follows:
sip:144.25.174.189:5060;transport=TCP;lr;appId=dialin,sip:144.25.174.189:5060; transport=TCP;lr;appId=proxyregistrar
Note:
The Proxy Registrar must always be the last item listed in the SIPUriList attribute.To ensure that applications that you deploy to the OCMS SIP servlet container are invoked in response to incoming requests, you must add any request-related application that you deploy to this list. The name of the application defined for the appId parameter (which is case-sensitive) can either be the full name of the deployed application, or an alias for the application. For an alias, the name must match the application alias set for the ApplicationAliases parameter of the SIP Servlet Container MBean. For more information on the SIP Servlet Container MBean and deploying applications to the OCMS SIP servlet container, see Oracle Communication and Mobility Server Administrator's Guide.
The deployment descriptor file enables application security through its <security-constraint> element. Security is declared per servlet by adding a <security-constraint> element to servlets that require authentication and authorization.
The <proxy-authentication/> element defines servlet authentication. If a servlet requires authentication, then it can request either 401 Response (Unauthorized), which is the default, or a 407 Response (Proxy Authentication Required).
A security constraint can hold one or more resource collections, <resourcecollection>, each indicating that the servlet requires authentication and the SIP methods that require authentication.
Users can have a single role, several roles, or no role at all. Each security constraint can set zero or one authorization constraints, <auth-constraint>, containing zero or more role names, <role-name>, that the authenticated user is authorized against. Authorization can, beside from inside the deployment descriptor, also be checked programmatically from inside a servlet. For example, the isUserInRole method on the SipServletRequest or the SipServletResponse object.
Example 3-3 illustrates a security constraint that requires authentication for MyServlet when the request is either an INVITE or a MESSAGE. There are no authorization constraints to any roles. An unauthenticated user receives 407 Response (Proxy Authentication Required) on its request if <proxy-authentication/> is set.
Example 3-3 Configuring Application Security
<security-constraint>
<display-name>MyServlet Security Constraint</display-name>
<resource-collection>
<resource-name>MyServletResource</resource-name>
<description>Securing MyServlet</description>
<servlet-name>MyServlet</servlet-name>
<sip-method>MESSAGE</sip-method>
<sip-method>INVITE</sip-method>
</resource-collection>
<proxy-authentication/>
<auth-constraint>
<role-name>*</role-name>
</auth-constraint>
</security-constraint>
If a SIP client sends a REGISTER request to a server as illustrated in Example 3-4, then a 401 (Unauthorized) message is returned to the client. If the authentication succeeds, then the roles of the user are checked against the role names set in the <auth-constraint>.
Example 3-4 Configuring Security Constraints
<security-constraint>
<display-name>MyServlet Security Constraint</display-name>
<resource-collection>
<resource-name>MyServletResource</resource-name>
<description>Securing MyServlet</description>
<servlet-name>MyServlet</servlet-name>
<sip-method>REGISTER</sip-method>
</resource-collection>
<auth-constraint>
<role-name>Location Service</role-name>
</auth-constraint>
</security-constraint>
If the user re-sends the REGISTER request which is subsequently authenticated, then then the container checks the roles of the user against the required Location Service role. A 403 Response (Forbidden) message is sent if the user does not have the appropriate role.
