Security role references

 

---

Webapp developers or EJB providers that use the available programmatic security J2EE APIs, isUserInRole(String roleName) or isCallerInRole(String roleName), use a role-name in the code.

The actual roles used in the deployed runtime environment may not be known until the Webapp and EJB components (for example, .war files and ejb-jar.jar files) are assembled into an .ear file. Therefore, the role-names used in the web application or EJB component code are "logical" role-names which the application assembler maps to the actual runtime environment roles during application assembly. The security role references provide a level of indirection that insulate web application component and EJB developers from having to know the actual roles in the runtime environment.

The definition of the "logical" roles and the mapping to the actual runtime environment roles are specified in the security-role-ref element of both the web application and the EJB jar file deployment descriptors, web.xml and ejb-jar.xml respectively. The Application Assembly Tool (AAT) can be used to both define the role-name and map them to the actual runtime roles in the environment with the role-link element.

The following is an example of a security-role-ref from an EJB ejb-jar.xml deployment descriptor.

<enterprise-beans>
    ... 
    <entity>
        <ejb-name>AardvarkPayroll</ejb name>
        <ejb-class>com.aardvark.payroll.PayrollBean</ejb-class>
        ...
        <security-role-ref>
            <description>
                The role has been linked to the payroll-department role. 
            </description>
            role-name>payroll</role-name>
            <role-link>payroll-department</role-link>
        </security-role-ref>
        ...
    </entity>
    ...
</enterprise-beans>

In the example above, the string payroll with appears in the <role-name> element, is what the EJB provider would use as the argument to isCallerInRole() API. The <role-link> element is what ties the logical role to the actual role used in the runtime environment.

Note that for EJBs, the security-role-ref must appear in the deployment descriptor even if the logical role-name is the same as the actual role name in the environment.

The rules for web application components are slightly different. If no security-role-ref element matching a security-role element has been declared, the container must default to checking the role-name element argument against the list of security-role elements for the web application. The isUserInRole method references the list to determine whether the caller is mapped to a security role. The developer must be aware that the use of this default mechanism may limit the flexibility in changing role names in the application without having to recompile the servlet making the call.

See the EJB 2.0 and Servlet 2.3 specification in "Security: Resources for Learning" for complete details on this specification.