The Java EE 5 Tutorial (PDF) - Oracle Software Downloads

Working with Realms, Users, Groups, and Roles
782
Mapping Roles to Users and Groups
When you are developing a Java EE application, you don’t need to know what categories of
users have been defined for the realm in which the application will be run. In the Java EE
platform, the security architecture provides a mechanism for mapping the roles defined in the
application to the users or groups defined in the runtime realm. To map a role name permitted
by the application or module to principals (users) and groups defined on the server, use the
security-role-mapping element in the runtime deployment descriptor
(sun-application.xml, sun-web.xml,orsun-ejb-jar.xml) file. The entry needs to declare a
mapping between a security role used in the application and one or more groups or principals
defined for the applicable realm of the Application Server. An example for the sun-web.xml file
is shown below:
DIRECTOR
mcneely
MANAGER
manager
The role name can be mapped to either a specific principal (user), a group, or both. The
principal or group names referenced must be valid principals or groups in the current default
realm of the Application Server. The role-name in this example must exactly match the
role-name in the security-role element of the corresponding web.xml file or the role name
defined in the @DeclareRoles or @RolesAllowed annotations.
Sometimes the role names used in the application are the same as the group names defined on
the Application Server. Under these circumstances, you can enable a default principal-to-role
mapping on the Application Server using the Admin Console. From the Admin Console, select
Configuration, then Security, then check the enable box beside Default Principal to Role
Mapping. If you need more information about using the Admin Console, see “Adding Users to
the Application Server” on page 779.
The Java EE 5Tutorial • June 2010