Roles, Principals, and Principal to Role Mapping

For applications, you define roles in @DeclareRoles annotations or the Java EE deployment descriptor file application.xml. You define the corresponding role mappings in the Enterprise Server deployment descriptor file sun-application.xml. For individually deployed web or EJB modules, you define roles in @DeclareRoles annotations or the Java EE deployment descriptor files web.xml or ejb-jar.xml. You define the corresponding role mappings in the Enterprise Server deployment descriptor files sun-web.xml or sun-ejb-jar.xml.

For more information regarding Java EE deployment descriptors, see the Java EE Specification. For more information regarding Enterprise Server deployment descriptors, see Appendix C, Elements of the Enterprise Server Deployment Descriptors, in Sun GlassFish Enterprise Server v3 Application Deployment Guide.

Each security-role-mapping element in the sun-application.xml, sun-web.xml, or sun-ejb-jar.xml file maps a role name permitted by the application or module to principals and groups. For example, a sun-web.xml file for an individually deployed web module might contain the following:

<sun-web-app>
    <security-role-mapping>
        <role-name>manager</role-name>
        <principal-name>jgarcia</principal-name>
        <principal-name>mwebster</principal-name>
        <group-name>team-leads</group-name>
    </security-role-mapping>
    <security-role-mapping>
        <role-name>administrator</role-name>
        <principal-name>dsmith</principal-name>
    </security-role-mapping>
</sun-web-app>

A role can be mapped to either specific principals or to groups (or both). The principal or group names used must be valid principals or groups in the realm for the application or module. Note that the role-name in this example must match the @DeclareRoles annotations or the role-name in the security-role element of the corresponding web.xml file.

You can also specify a custom principal implementation class. This provides more flexibility in how principals can be assigned to roles. A user's JAAS login module now can authenticate its custom principal, and the authenticated custom principal can further participate in the Enterprise Server authorization process. For example:

<security-role-mapping>
    <role-name>administrator</role-name>
    <principal-name class-name="CustomPrincipalImplClass">
        dsmith
    </principal-name>
</security-role-mapping>

You can specify a default principal and a default principal to role mapping, each of which applies to the entire Enterprise Server. The default principal to role mapping maps group principals to the same named roles. Web modules that omit the run-as element in web.xml use the default principal. Applications and modules that omit the security-role-mapping element use the default principal to role mapping. These defaults are part of the Security Service, which you can access in the following ways:

• In the Administration Console, select the Security component under the relevant configuration. For details, click the Help button in the Administration Console.

• Use the asadmin set command. For details, see the Sun GlassFish Enterprise Server v3 Reference Manual. For example, you can set the default principal as follows.

  asadmin set server-config.security-service.default-principal=dsmith
  asadmin set server-config.security-service.default-principal-password=secret

  You can set the default principal to role mapping as follows.

  asadmin set server-config.security-service.activate-default-principal-to-role-mapping=true
  asadmin set server-config.security-service.mapped-principal-class=CustomPrincipalImplClass