Mapping Roles to Users and Groups

<< Defining Security Roles | Establishing a Secure Connection >>

Mapping Roles to Users and Groups

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, or sun-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:

<sun-web-app>

<security-role-mapping>

<role-name>DIRECTOR</role-name>

<principal-name>mcneely</principal-name>

</security-role-mapping>

<security-role-mapping>

<role-name>MANAGER</role-name>

<group-name>manager</group-name>

</security-role-mapping>

</sun-web-app>

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 781

Working with Realms, Users, Groups, and Roles

The Java EE 5 Tutorial · September 2007

784