Skip Headers

Oracle® Communication and Mobility Server Developer's Guide Release 10.1.3 Part Number E10293-02 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# 3 Advanced SIP Servlet Configuration

This chapter describes advanced topics related to SIP servlets through the following sections:

- Using the appId Parameter to Set Addresses for SIP Applications

- Configuring Application Security

## Using the appId Parameter to Set Addresses for SIP Applications

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 `appId`s 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.

### Configuring the appId Parameter

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

Description of "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 `appId`s 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.

#### Adding Deployed Applications to 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.

## Configuring Application Security

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.