Simplified Security Role Mapping

In Java EE applications, security roles are used to restrict access to resources. A typical example is to limit access to parts of a business web site to users who are in the role "customers," while allowing users in the role "suppliers" access to other parts of the site. The application developer can specify which URLs or EJB methods can be accessed by users in which roles, and can programmatically make security decisions based on user roles at runtime. So a role is a logical privilege that can be granted to (or withheld from) users to control access within an application.

The identities of the users are stored in the application server as principals (also called "users"), which can belong to groups. Thus the privileges represented by the roles can be mapped to actual users by mapping the roles to principals or groups. This decoupling of the application's roles and the container's principals/groups allows the same application to be deployed on different servers without any changes to the code. Only the security role mapping needs to be changed in the deployment descriptor (for GlassFish, this is in sun-application.xml, sun-web.xml, or sun-ejb-jar.xml). The deployer could map the role "suppliers" (continuing above example) to an existing group "partners," a principal "admin," or even a group with the same name "suppliers." In this last case, a simplification can be made such that the default principal to role mapping is used and no role mapping is required in the deployment descriptor. This can be useful when you are writing an application and already know which groups are used in the server to which you will be deploying.

For more information on the roles and groups, please see Shing Wai's blog assign-groups in GlassFish Security realm.

The following is a simple web example that uses default principal to role mapping and so does not use a <security-role-mapping> element in the sun-web.xml file. In fact, it does not use sun-web.xml at all. To add a user and group for this example, open the admin console (normally localhost:4848) and choose: Configuration -> Security -> Realms -> file in the tree in the left pane. Then, in the right-hand pane, click Manage Users. Click New, enter "sparky" for User ID, add "users" to the Group List, and use "ee" for a password. Click OK.

This application consists of a simple jsp page, and it can only be accessed by someone in the role "users" (which matches the group "users" created above). This is the entire page, index.jsp:

<%@page contentType="text/html"%>
<%@page pageEncoding="UTF-8"%>
<DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        <h2>Hello ${pageContext.request.remoteUser}</h2>

This is the entire web.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="" xmlns:xsi="" xsi:schemaLocation="h

To create the application, save index.jsp into a directory, create a subdirectory "WEB-INF" and save web.xml into it, and create the war file: 'jar cvf test.war \*' The war file can also be downloaded here.

Because security role mapping happens at deployment time, the default mapping must be turned on before the application is deployed. To turn on the default mapping, choose Configuration -> Security in the admin console. Click Enabled next to Default Principal to Role Mapping and Save.

Then the example war file can be deployed through the admin console or with 'asadmin deploy test.war'. When you attempt to reach the page in your browser (for instance with http://localhost:8080/test), you will be prompted for username and password. Entering "sparky" and "ee" should take you to a page with Hello sparky. The example works because the same string is used for both role and group, and so any user in the group "users" will also be in the role "users."


Thanks for this post!

This was the last step I needed to fully migrate away from Apache as GlassFish really is much faster!

Posted by Wes Williams on April 25, 2007 at 10:18 AM EST #

Thanks Wes, that's really good to hear!

Posted by Bobby Bissett on April 27, 2007 at 02:57 AM EST #

Great work Bobby. Wes, wonderful to have you part of the Glassfish Community!!

Posted by Tom Kincaid on April 27, 2007 at 03:43 AM EST #


Posted by gf on June 22, 2007 at 04:43 PM EST #

Thanks a lot for this tip! jBPM 3.2.3 console customized for tomcat is know running within glassfish with no further adoptions.

Posted by Thomas Kriechbaum on November 04, 2008 at 09:43 AM EST #

Good to hear it! Glad this helped you (and good to hear another story of something moving easily from Tomcat to GlassFish).

Posted by Bobby Bissett on November 12, 2008 at 01:56 AM EST #

Hmm... I did everything, but it's not working for me.

Posted by iresha on December 06, 2009 at 04:52 PM EST #

Iresha, you should probably send a message to the GlassFish users list with more information: what version of GlassFish you're using, what's in your web.xml file, and what problem exactly that you're seeing. Good luck!

Posted by Bobby on December 07, 2009 at 03:06 AM EST #

Post a Comment:
Comments are closed for this entry.

Whatever part of GlassFish or the Java EE world that catches my attention. (Also, go Red Sox.)


« June 2016