java - Glassfish 3.1 default principal to role mapping

Question

I am working with glassfish and jaas module.

I configured my web.xml in this way.

<security-constraint>
    <web-resource-collection>
        <web-resource-name>ALL Page for admin</web-resource-name>
        <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>user</role-name>
    </auth-constraint>
</security-constraint>
<login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>file</realm-name>
</login-config>
<security-role>
    <description>Administrator</description>
    <role-name>user</role-name>
</security-role>

It means all user that want to access my web application need be of the group user.

Then on the glassfish console I need to tick the options in: Configuration -> server-config -> security -> Default Principal To Role Mapping

My question is why I need to tick this Default Principal to Role Mapping ? And how I can change my web.xml to avoid to tick it ?

Thanks a lot

Loic

Answer 1

When you specify the roles and roles in web.xml you are using declarative security, which essentially relies on the use of JAAS to enforce authentication and authorization requirements specified declaratively.

The roles specified in the deployment descriptors are merely representations of the roles that are used in the application. These roles need not be the same as the ones present in the user-identity database (or authentication realm) used at runtime, and usually these might be different, for development of the application may have been undertaken without any regard to the actual users and groups present in the user-identity database.

Typically a mapping is performed between the declarative roles specified in web.xml and the principals or groups present in the user-identity database using the container specific deployment descriptors. In Glassfish 3,1, this happens to be the glassfish-web.xml file. Each such mapping would map a declarative role in the application, to either a principal or a group in a JAAS realm, in the following manner in either glassfish-web.xml (for WAR file deployments) or glassfish-application.xml (for EAR file deployments), or glassfish-ejb-jar.xml (for EJB JAR file deployments):

glassfish-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glassfish-web-app PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Servlet 3.0//EN" "http://glassfish.org/dtds/glassfish-web-app_3_0-1.dtd">
<glassfish-web-app error-url="">
...
    <security-role-mapping>
        <role-name>user</role-name>
        <principal-name>Root</principal-name> <!-- Map a principal to the role 'user' -->
        <group-name>Administrators</group-name> <!-- Map a group to the role 'user' -->
    </security-role-mapping>
...
</glassfish-web-app>

glassfish-application.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glassfish-application PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Java EE Application 6.0//EN" "http://glassfish.org/dtds/glassfish-application_6_0-1.dtd">
<glassfish-application>
...
    <security-role-mapping>
        <role-name>user</role-name>
        <principal-name>Root</principal-name> <!-- Map a principal to the role 'user' -->
        <group-name>Administrators</group-name> <!-- Map a group to the role 'user' -->
    </security-role-mapping>
...
</glassfish-application>

glassfish-ejb-jar.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glassfish-ejb-jar PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 EJB 3.1//EN" "http://glassfish.org/dtds/glassfish-ejb-jar_3_1-1.dtd">
<glassfish-ejb-jar>
...
    <security-role-mapping>
        <role-name>user</role-name>
        <principal-name>Root</principal-name> <!-- Map a principal to the role 'user' -->
        <group-name>Administrators</group-name> <!-- Map a group to the role 'user' -->
    </security-role-mapping>
...
</glassfish-ejb-jar>

The above descriptors map a role user to a Principal with individual identity of name Root and to a user group with name Administrators in the realm. You can omit either of these mappings, and retain only a role to principal mapping, or a role to group mapping. You may also have multiple principals mapped to the same role, or multiple groups mapped to the same role, or even multiple principals and groups mapped to the same role.

It is important to understand the concept of principals and groups in JAAS realms - a principal represents the identity of a Subject (the user logging into the application) in the system, and it could be an individual identity (a single user) or a group identity (a user group). By mapping the declarative roles to the actual principals or groups, one would be able to enforce rules specified in the web.xml against any user-identity database (i.e. any realm), and be able to do so dynamically without any changes in the codebase; after all, such a change would require re-mapping the declarative roles to the new set of principals and groups, in a possibly different realm. You can find a basic tutorial on how Java EE security and JAAS work together in the chapter on security in the Java EE 6 tutorial.

Glassfish allows for a simplified mapping scheme, where it is not necessary to perform the mapping for all declarative roles in the container-specific deployment descriptor (in this case glassfish-web.xml), as long as the names of the declarative roles happen to be similar to the names of the principals or groups. This is the default principal to role mapping scheme. It appears that in your case, the principals/groups in your realm are the same as the declarative roles specified in web.xml, and hence you would avoid mapping the roles to principals and groups explicitly. In simpler words, if the role user is the same as a principal user or a usergroup user in your JAAS realm (and similarly for other identities), then you can use the default role to principal mapping scheme of Glassfish, without mapping this for every role in your web.xml file.

If you wish to avoid ticking the deployment option of default principal to role mapping, then you must provide the role to principal/group mapping yourself in the container specific deployment descriptors, as you would normally do for other application servers.

You could read more about this topic in one of the posts on blogs.oracle.com that describes this feature of Glassfish.