Assigning Roles Using security-role-assignment

Important Requirements

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>

Example 14-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>

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 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 shows an example security-role-assignment element. This example assigns three users to the roleadmin role defined in Example 14-1. To change the role assignment, you must edit the weblogic.xml descriptor and redeploy the SIP Servlet.

Dynamically Assigning Roles Using the Administration 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 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. 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.

Example 14-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>