The following sections describe how to apply security constraints to SIP Servlet resources when deploying to Oracle Communications Converged Application Server:
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 Server 10g Release 3 documentation:
run-as
element used for propagating roles to called EJBs.
See also the example sip.xml
excerpt in
Listing 9-1, Declarative Security Constraints in sip.xml, on page 9-5.
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. Oracle Communications 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:
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.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 Oracle Communications Converged Application Server role assignment in more detail.
With implicit role assignment, Oracle Communications Converged Application Server assigns a security-role
name in sip.xml
to a role of the exact same name, which should be configured in the Oracle Communications 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
, Oracle Communications Converged Application Server 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. Oracle Communications Converged Application Server 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 Oracle Communications 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 weblogic.xml
, Oracle Communications 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 , Oracle Communications Converged Application Server generates the error message: |
Note: | The security-role-assignment references an invalid security-role: rolename |
Note: | 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, Listing 9-1 shows a portion of a sip.xml
deployment descriptor that defines a security constraint with the role, roleadmin
. Listing 9-2 shows that a security-role-assignment
element has been defined in weblogic.xml
to assign principals and roles to roleadmin
. In Oracle Communications Converged Application Server, this Servlet must be deployed with a web.xml
deployment descriptor that also defines the roleadmin
role, as shown in
Listing 9-3.
If the web.xml
contents were not available, Oracle Communications 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.
...
<security-constraint>
<resource-collection>
<resource-name>RegisterRequests</resource-name>
<servlet-name>registrar</servlet-name>
</resource-collection>
<auth-constraint>
<role-name>roleadmin</role-name>
</auth-constraint>
</security-constraint>
<security-role>
<role-name>roleadmin</role-name>
</security-role>
...
<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>
<!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>
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 Oracle Communications Converged Application Server security realm. If the security-role
is used in combination with the run-as
element in sip.xml
, Oracle Communications Converged Application Server assigns the first principal or role name specified in the security-role-assignment
to the run-as
role.
Listing 9-2, Example security-role-assignment in weblogic.xml, on page 9-5 shows an example security-role-assignment
element. This example assigns three users to the roleadmin
role defined in
Listing 9-1, Declarative Security Constraints in sip.xml, on page 9-5. 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 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: |
Listing 9-4 shows an example of using the externally-defined
element with the roleadmin
role defined in
Listing 9-1, Declarative Security Constraints in sip.xml, on page 9-5. To assign existing principals and roles to the roleadmin
role, the Administrator would use the Oracle Communications Converged Application Server Administration Console.
See Users, Groups, and Security Roles in the Oracle WebLogic Server 10g Release 3 documentation for information about adding and modifying security roles using the Administration Console.
<weblogic-web-app>
<security-role-assignment>
<role-name>webuser</role-name>
<externally-defined/>
</security-role-assignment>
</weblogic-web-app>
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.
Oracle Communications 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:
weblogic.xml
assigns a sip.xml
role in a security-role-assignment
element, the security-role-assignment
is used.Note: | Oracle Communications Converged Application Server also requires a role definition in web.xml in order to use a security-role-assignment . See
Important Requirement for Oracle Communications Converged Application Server. |
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:
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: | Oracle Communications Converged Application Server also requires a role definition in web.xml in order to assign roles with run-as-principal-name . See
Important Requirement for Oracle Communications Converged Application Server. |
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: | Oracle Communications Converged Application Server also requires a role definition in web.xml in order to assign roles with run-as-role-assignment . See
Important Requirement for Oracle Communications Converged Application Server. |
weblogic.xml
assigns a sip.xml run-as
role in a security-role-assignment
element, the security-role-assignment
is used.Note: | Oracle Communications Converged Application Server also requires a role definition in web.xml in order to use a security-role-assignment . See
Important Requirement for Oracle Communications Converged Application Server. |
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 Oracle Communications Converged Application Server. Using this debug option causes Oracle Communications 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 the Oracle WebLogic Server 10g Release 3 documentation.