| Oracle® Communication and Mobility Server Developer Guide Release 10.1.3 Part Number B31511-01 |
|
|
View PDF |
| Oracle® Communication and Mobility Server Developer Guide Release 10.1.3 Part Number B31511-01 |
|
|
View PDF |
This chapter, describes advanced topics related to SIP Servlets. It contains the following sections:
Because JSR 116 does not state how to address a SIP Application, OCMS includes a parameter called appId, which is located either in the URI of the top-most route header (Example 3-1), or in the REQUEST URI (Example 3-2). The SIP container checks both of these locations for this parameter.
If the SIP Container locates appId, it interprets the value defined for appId as the name of the application to invoke. The 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. For example, if the SIP 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), because it cannot find an application with this name. 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.
The container will only consider the appId if this parameter is included in the top-most-route and this route points to the container, or if there are no route headers present, the request-uri.
Note:
You can configure the route to point to the SIP Container through the SipServletContainer MBean.In Example 3-1, there is a route header present in the request and if the container has been configured to acknowledge the ip-address 192.168.0.100 as an address pointing to itself, it will use the appId in the route-header and invoke the application "presence". However, if this IP address does not belong to the container, it will simply ignore the appId and invoke the default application as previously described.
Example 3-1 appId Defined in the Route Header of an Incoming Request
SUBSCRIBE sip:bob@example.com To: . From: . Route: <sip:192.168.0.100:5060;appId=presence>
It is important to realize that if the appId would have been present in the request-uri instead, the container would not even had considered evaluating the request-uri for the presence of an appId parameter since the request did contain route-headers. Example 3-2 illustrates how the appId would have been ignored by the container even though the request-uri is pointing to the container itself.
Example 3-2 appId in the Request URI of an Incoming Request
SUBSCRIBE sip:bob@192.168.0.100;appId=presence To: . From: . Route: <sip:192.168.0.200:5060>
The reason for this is that even though the final destination would be the container itself, this message must first be routed through the server at 192.168.0.200 before coming back to this container where the application presence would be invoked. Of course, depending on the application on the other server, this request may or may not be proxied back to us (that application might e.g. terminate the request by sending a final response to this message).
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 (Unauthorized), which is the default, or a 407 (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 roles 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 (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 (Forbidden) message is sent as a response if the user does not have the appropriate role.
