This chapter describes how to apply security constraints to Session Initiation Protocol (SIP) Servlet resources when deploying to Oracle Communications Converged Application Server.
The SIP Servlet application program interface (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.
For SIP servlet Plain Old Java Objects (POJOs), annotations available which provide identical functionality:
@SipSecurity: specifies security constraints to be enforced on SIP protocol messages.
@SipConstraint: used within the @SipSecurity annotation to represent the security constraint to be applied to all SIP protocol methods for which a corresponding @SipMethodConstraint does not occur within the @SipSecurity annotation.
@SipMethodConstraint: used within the @SipSecurity annotation to represent security constraints on specific SIP protocol messages.
For information on using the @SipSecurity annotation see section 22.3.10.1 in JSR-359, https://jcp.org/en/jsr/detail?id=359
.
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.
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 Server documentation:
The discussion on securing web applications in Programming WebLogic Security provides an overview of declarative and programmatic security models for Servlets.
The discussion on EJB security-related deployment descriptors in ”Securing Enterprise JavaBeans (EJBs)” in Programming WebLogic Security 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 14-1, "Declarative Security Constraints in sip.xml".
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.
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>
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. Converged Application Server 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. 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 the sip.xml and weblogic.xml deployment descriptors, 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 the sip.xml deployment descriptor's 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 Converged Application Server role assignment in more detail.
With implicit role assignment, Converged Application Server assigns a security-role
name in sip.xml to a role of the exact same name, which must be configured in the Converged Application Server 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, Converged Application Server implicitly maps the sip.xml deployment descriptor's 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. Converged Application Server displays 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 Converged Application Server 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.
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.
If you specify a security-role-assignment
element in the weblogic.xml deployment descriptor, Converged Application Server 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, Converged Application Server generates the error message:The security-role-assignment references an invlaid 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 14-1 shows a portion of a sip.xml deployment descriptor that defines a security constraint with the role, roleadmin
. Example 14-2 shows that a security-role-assignment
element has been defined in weblogic.xml to assign principals and roles to roleadmin
. In Converged Application Server, this Servlet must be deployed with a web.xml deployment descriptor that also defines the roleadmin
role, as shown in Example 14-3.
If the web.xml contents were not available, Converged Application Server 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 14-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 14-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>
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 Converged Application Server security realm. If the security-role
is used in combination with the run-as
element in sip.xml, Converged Application Server assigns the first principal or role name specified in the security-role-assignment
to the run-as
role.
Example 14-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 14-1, "Declarative Security Constraints in sip.xml". To change the role assignment, you must edit the weblogic.xml descriptor and redeploy the SIP Servlet.
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 on the Security control panel in 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 14-4 shows an example of using the externally-defined
element with the roleadmin
role defined in Example 14-1, "Declarative Security Constraints in sip.xml". To assign existing principals and roles to the roleadmin
role, the Administrator would use the Converged Application Server Administration Console.
See ”Users, Groups, and Security Roles” in Securing Resources Using Roles and Policies for Oracle WebLogic Server for information about adding and modifying security roles by using the Administration Console.
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.
Example 14-5 shows an example of a configured run-as role in a sip.xml descriptor.
Example 14-5 run-as Roles in sip.xml
... <servlet> <servlet-name>myservlet</servlet-name> <servlet-class>com.mycompany.MyServlet</servlet-class> <run-as> <role-name>weblogic</role-name> </run-as> </servlet> ...
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.
Converged Application Server 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:
Converged Application Server 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 the sip.xml deployment descriptor's run-as
role in a run-as-principal-name
element defined within servlet-descriptor
, the run-as-principal-name
assignment is used.
Note:
Converged Application Server 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 the sip.xml deployment descriptor's run-as
role in a run-as-role-assignment
element, the run-as-role-assignment
element is used.
Note:
Converged Application Server also requires a role definition in web.xml in order to assign roles withrun-as-role-assignment
. See "Important Requirements".If weblogic.xml assigns the sip.xml deployment descriptor's run-as
role in a security-role-assignment
element, the security-role-assignment
is used.
Note:
Converged Application Server also requires a role definition in web.xml in order to use asecurity-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.
If you want to debug security features in SIP Servlets that you develop, specify the -Dweblogic.Debug=wlss.Security startup
option when you start Converged Application Server. Using this debug option causes Converged Application Server to display additional security-related messages in the standard output.
The weblogic.xml DTD contains detailed information about each of the role mapping elements discussed in this section. See ”weblogic.xml Deployment Descriptor Elements” in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.