Security role references:

Security role references

Webapp developers or EJB providers that use programmatic security in the form of isUserInRole(String roleName) or isCallerInRole(String roleName), use a role-name in the code.
The actual roles used in the deployed run-time environment might not be known until *.war and ejb-jar.jar are assembled into an ear file, therefore, logical role names are used, with actual run-time environment roles mapped during application assembly. The security role references provide a level of indirection that insulate Webapp component and EJB developers from having to know the actual roles in the run-time environment.
The definition of the logical roles and the mapping to the actual run-time environment roles are specified in the security-role-ref element of both the Webapp and the EJB JAR file deployment descriptors, web.xml and ejb-jar.xml respectively. Use the Application Assembly Tool (AAT) to define the role names and map them to the actual run-time 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.PayrollBeanejb-class>com.aardvark.payroll.PayrollBean> 
...
<security-role-ref>
<description>
This role should be assigned to the employees of the payroll department. Members of this role have access to the payroll record of everyone. The role has been linked to the payroll-department role. This role should be assigned to the employees of the payroll department. Members of this role have access to the payroll record of everyone. 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 previous example, the string payroll , which appears in the <role-name> element, is what the EJB provider uses as the argument to the isCallerInRole() API. The <role-link> element is what ties the logical role to the actual role used in the run-time environment.
Note that for enterprise beans, the security-role-ref element 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 Webapp components are slightly different. If no security-role-ref element matching a security-role element is declared, the container must default to checking the role-name element argument against the list of security-role elements for the Webapp. 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 can limit the flexibility in changing role names in the application without having to recompile the servlet making the call.
See the EJB Version 2.0 and Servlet Version 2.3 specification in the Security: Resources for Learning article for complete details on this specification.
Security: Links