6 Securing SIP Servlet Resources

The chapter describes how to apply security constraints to SIP Servlet resources when deploying to OWLCS, in the following sections:

Section 6.1, "Overview of SIP Servlet Security"
Section 6.2, "Triggering SIP Response Codes"
Section 6.3, "Specifying the Security Realm"
Section 6.4, "Role Mapping Features"
Section 6.5, "Using Implicit Role Assignment"
Section 6.6, "Assigning Roles Using security-role-assignment"
Section 6.7, "Assigning run-as Roles"
Section 6.8, "Role Assignment Precedence for SIP Servlet Roles"
Section 6.9, "Debugging Security Features"
Section 6.10, "weblogic.xml Deployment Descriptor Reference"

6.1 Overview of SIP Servlet Security

The SIP Servlet API specification defines a set of deployment descriptor elements that can be used for providing declarative and programmatic security for SIP Servlets. The primary method for declaring security constraints is to define one or more security-constraint elements in the sip.xml deployment descriptor. The security-constraint element defines the actual resources in the SIP Servlet, defined in resource-collection elements, that are to be protected. security-constraint also identifies the role names that are authorized to access the resources. All role names used in the security-constraint are defined elsewhere in sip.xml in a security-role element.

SIP Servlets can also programmatically refer to a role name within the Servlet code, and then map the hard-coded role name to an alternate role in the sip.xml security-role-ref element during deployment. Roles must be defined elsewhere in a security-role element before they can be mapped to a hard-coded name in the security-role-ref element.

The SIP Servlet specification also enables Servlets to propagate a security role to a called Enterprise JavaBean (EJB) using the run-as element. Once again, roles used in the run-as element must be defined in a separate security-role element in sip.xml.

Chapter 14 in the SIP Servlet API specification provides more details about the types of security available to SIP Servlets. SIP Servlet security features are similar to security features available with HTTP Servlets; you can find additional information about HTTP Servlet security by referring to these sections in the Oracle WebLogic Communication Services documentation:

Securing Web Applications in Programming WebLogic Security provides an overview of declarative and programmatic security models for Servlets.
EJB Security-Related Deployment Descriptors in Securing Enterprise JavaBeans (EJBs) describes all security-related deployment descriptor elements for EJBs, including the run-as element used for propagating roles to called EJBs.

See also the example sip.xml excerpt in Example 6-1, "Declarative Security Constraints in sip.xml".

6.2 Triggering SIP Response Codes

You can distinguish whether you are a proxy application, or a UAS application, by configuring the container to trigger the appropriate SIP response code, either a 401 SIP response code, or a 407 SIP response code. If your application needs to proxy an invitation, the 407 code is appropriate to use. If your application is a registrar application, you must use the 401 code.

To configure the container to respond with a 407 SIP response code instead of a 401 SIP response code, you must add the <proxy-authentication> element to the security constraint.

6.3 Specifying the Security Realm

You must specify the name of the current security realm in the sip.xml file as follows:

<login-config>
<auth-method>DIGEST</auth-method> 
<realm-name>myrealm</realm-name>
</login-config>

6.4 Role Mapping Features

When you deploy a SIP Servlet, security-role definitions that were created for declarative and programmatic security must be assigned to actual principals and/or roles available in the Servlet container. OWLCS uses the security-role-assignment element in weblogic.xml to help you map security-role definitions to actual principals and roles. security-role-assignment provides two different ways to map security roles, depending on how much flexibility you require for changing role assignment at a later time:

The security-role-assignment element can define the complete list of principal names and roles that map to roles defined in sip.xml. This method defines the role assignment at deployment time, but at the cost of flexibility; to add or remove principals from the role, you must edit weblogic.xml and redeploy the SIP Servlet.
The externally-defined element in security-role-assignment enables you to assign principal names and roles to a sip.xml role at any time using the Administration Console. When using the externally-defined element, you can add or remove principals and roles to a sip.xml role without having to redeploy the SIP Servlet.

Two additional XML elements can be used for assigning roles to a sip.xml run-as element: run-as-principal-name and run-as-role-assignment. These role assignment elements take precedence over security-role-assignment elements if they are used, as described in "Assigning run-as Roles".

Optionally, you can choose to specify no role mapping elements in weblogic.xml to use implicit role mapping, as described in "Using Implicit Role Assignment".

The sections that follow describe OWLCS role assignment in more detail.

6.5 Using Implicit Role Assignment

With implicit role assignment, OWLCS assigns a security-role name in sip.xml to a role of the exact same name, which must be configured in the OWLCS security realm. To use implicit role mapping, you omit the security-role-assignment element in weblogic.xml, as well as any run-as-principal-name, and run-as-role-assignment elements use for mapping run-as roles.

When no role mapping elements are available in weblogic.xml, OWLCS implicitly maps sip.xml security-role elements to roles having the same name. Note that implicit role mapping takes place regardless of whether the role name defined in sip.xml is actually available in the security realm. OWLCS display a warning message anytime it uses implicit role assignment. For example, if you use the "everyone" role in sip.xml but you do not explicitly assign the role in weblogic.xml, the server displays the warning:

<Webapp: ServletContext(id=id,name=application,context-path=/context), the role: everyone defined in web.xml has not been mapped to principals in security-role-assignment in weblogic.xml. Will use the rolename itself as the principal-name.>

You can ignore the warning message if the corresponding role has been defined in the OWLCS security realm. The message can be disabled by defining an explicit role mapping in weblogic.xml.

Use implicit role assignment if you want to hard-code your role mapping at deployment time to a known principal name.

6.6 Assigning Roles Using security-role-assignment

The security-role-assignment element in weblogic.xml enables you to assign roles either at deployment time or at any time using the Administration Console. The sections that follow describe each approach.

6.6.1 Important Requirements

If you specify a security-role-assignment element in weblogic.xml, OWLCS requires that you also define a duplicate security-role element in a web.xml deployment descriptor. This requirement applies even if you are deploying a pure SIP Servlet, which would not normally require a web.xml deployment descriptor (generally reserved for HTTP Web Applications).

Note:

If you specify a security-role-assignment in weblogic.xml but there is no corresponding security-role element in web.xml, OWLCS generates the error message:

The security-role-assignment references an invalid security-role: rolename

The server then implicitly maps the security-role defined in sip.xml to a role of the same name, as described in "Using Implicit Role Assignment".

For example, Example 6-1 shows a portion of a sip.xml deployment descriptor that defines a security constraint with the role, roleadmin. Example 6-2 shows that a security-role-assignment element has been defined in weblogic.xml to assign principals and roles to roleadmin. In OWLCS, this Servlet must be deployed with a web.xml deployment descriptor that also defines the roleadmin role, as shown in Example 6-3.

If the web.xml contents were not available, OWLCS would use implicit role assignment and assume that the roleadmin role was defined in the security realm; the principals and roles assigned in weblogic.xml would be ignored.

Example 6-1 Declarative Security Constraints in sip.xml

...
  <security-constraint>
      <resource-collection>
      <resource-name>RegisterRequests</resource-name>
      <servlet-name>registrar</servlet-name>
    </resource-collection>
    <auth-constraint>
      <javaee:role-name>roleadmin</javaee:role-name>
    </auth-constraint>
  </security-constraint>

  <security-role>
    <javaee:role-name>roleadmin</javaee:role-name>
  </security-role>
...

Example 6-2 Example security-role-assignment in weblogic.xml

<weblogic-web-app>
  <security-role-assignment>
       <role-name>roleadmin</role-name>
       <principal-name>Tanya</principal-name>
       <principal-name>Fred</principal-name>
       <principal-name>system</principal-name>
  </security-role-assignment>
</weblogic-web-app>

Example 6-3 Required security-role Element in web.xml

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
  <security-role>
    <role-name>roleadmin</role-name>
  </security-role>
</web-app>

6.6.2 Assigning Roles at Deployment Time

A basic security-role-assignment element definition in weblogic.xml declares a mapping between a security-role defined in sip.xml and one or more principals or roles available in the OWLCS security realm. If the security-role is used in combination with the run-as element in sip.xml, OWLCS assigns the first principal or role name specified in the security-role-assignment to the run-as role.

Example 6-2, "Example security-role-assignment in weblogic.xml" shows an example security-role-assignment element. This example assigns three users to the roleadmin role defined in Example 6-1, "Declarative Security Constraints in sip.xml". To change the role assignment, you must edit the weblogic.xml descriptor and redeploy the SIP Servlet.

6.6.3 Dynamically Assigning Roles Using the Administrative Console

The externally-defined element can be used in place of the <principal-name> element to indicate that you want the security roles defined in the role-name element of sip.xml to use mappings that you assign in the Administration Console. The externally-defined element gives you the flexibility of not having to specify a specific security role mapping for each security role at deployment time. Instead, you can use the Administration Console to specify and modify role assignments at anytime.

Additionally, because you may elect to use this element for some SIP Servlets and not others, it is not necessary to select the ignore roles and polices from DD option for the security realm. (You select this option in the On Future Redeploys: field on the General tab of the Security->Realms->myrealm control panel on the Administration Console.) Therefore, within the same security realm, deployment descriptors can be used to specify and modify security for some applications while the Administration Console can be used to specify and modify security for others.

Note:

When specifying security role names, observe the following conventions and restrictions:

The proper syntax for a security role name is as defined for an Nmtoken in the Extensible Markup Language (XML) recommendation available on the Web at: http://www.w3.org/TR/REC-xml#NT-Nmtoken.
Do not use blank spaces, commas, hyphens, or any characters in this comma-separated list: \t, < >, #, |, &, ~, ?, ( ), { }.
Security role names are case sensitive.
The Oracle-suggested convention for security role names is that they be singular.

Example 6-4 shows an example of using the externally-defined element with the roleadmin role defined in Example 6-1, "Declarative Security Constraints in sip.xml". To assign existing principals and roles to the roleadmin role, the Administrator would use the OWLCS Administration Console.

See the "Users, Groups, and Security Roles" for information about adding and modifying security roles using the Administration Console.

Example 6-4 Example externally-defined Element in weblogic.xml

<weblogic-web-app>
     <security-role-assignment>
         <role-name>webuser</role-name>
         <externally-defined/>
     </security-role-assignment>
</weblogic-web-app>

6.7 Assigning run-as Roles

The security-role-assignment described in "Assigning Roles Using security-role-assignment" can be also be used to map run-as roles defined in sip.xml. Note, however, that two additional elements in weblogic.xml take precedence over the security-role-assignment if they are present: run-as-principal-name and run-as-role-assignment.

run-as-principal-name specifies an existing principle in the security realm that is used for all run-as role assignments. When it is defined within the servlet-descriptor element of weblogic.xml, run-as-principal-name takes precedence over any other role assignment elements for run-as roles.

run-as-role-assignment specifies an existing role or principal in the security realm that is used for all run-as role assignments, and is defined within the weblogic-web-app element.

See "weblogic.xml Deployment Descriptor Reference" for more information about individual weblogic.xml descriptor elements. See also "Role Assignment Precedence for SIP Servlet Roles" for a summary of the role mapping precedence for declarative and programmatic security as well as run-as role mapping.

6.8 Role Assignment Precedence for SIP Servlet Roles

OWLCS provides several ways to map sip.xml roles to actual roles in the SIP Container during deployment. For declarative and programmatic security defined in sip.xml, the order of precedence for role assignment is:

If weblogic.xml assigns a sip.xml role in a security-role-assignment element, the security-role-assignment is used.

Note:
OWLCS also requires a role definition in web.xml in order to use a security-role-assignment. See "Important Requirements".
If no security-role-assignment is available (or if the required web.xml role assignment is missing), implicit role assignment is used.

For run-as role assignment, the order of precedence for role assignment is:

If weblogic.xml assigns a sip.xml run-as role in a run-as-principal-name element defined within servlet-descriptor, the run-as-principal-name assignment is used.

Note:
OWLCS also requires a role definition in web.xml in order to assign roles with run-as-principal-name. See "Important Requirements".
If weblogic.xml assigns a sip.xml run-as role in a run-as-role-assignment element, the run-as-role-assignment element is used.

Note:
OWLCS also requires a role definition in web.xml in order to assign roles with run-as-role-assignment. See "Important Requirements"
If weblogic.xml assigns a sip.xml run-as role in a security-role-assignment element, the security-role-assignment is used.

Note:
OWLCS also requires a role definition in web.xml in order to use a security-role-assignment. See "Important Requirements".
If no security-role-assignment is available (or if the required web.xml role assignment is missing), implicit role assignment is used.

6.9 Debugging Security Features

If you want to debug security features in SIP Servlets that you develop, specify the -Dweblogic.Debug=wlss.Security startup option when you start OWLCS. Using this debug option causes OWLCS to display additional security-related messages in the standard output.

6.10 weblogic.xml Deployment Descriptor Reference

The weblogic.xml DTD contains detailed information about each of the role mapping elements discussed in this section. See "weblogic.xml Deployment Descriptor Elements" for more information.