In an application, a role is an abstract name for a group of users. A role can be compared to a key that can open a lock. Many people might have a copy of the key. The lock doesn’t care who you are, only that you have the right key.
For example, in a corporation, you might have the roles Director, Manager, HR, and Employee. When an application developer is creating an internal payroll website, the developer would use the same set of data for all of its corporate users, but would allow different access to the data depending on the role the user is in. For example, a person in the role of HR would have permission to create new Employees, and to modify the payroll information for Employees. The Employee would be able to view their own payroll information, but would not be able to change some of the data, such as their pay rate, but could change some other data, such as their address or dependent information. The users' assigned role determines what permissions that user is granted for access to a particular set of resources in an application.
The following elements in a deployment descriptor use security roles in some capacity:
<security-role>
A security role element is used to define the security roles that will comprise the entire set of security roles used in the application. The sub-element role-name designates the name of the security role. All role names that are used in an application should be specified in its deployment descriptor.
<security-role-ref>
The security role reference element is used in conjunction with the HttpServletRequest.isUserInRole(String role) programmatic security option. When a call is made to isUserInRole, the caller identity is tested for membership in this role. If a security-role-ref has been defined, the caller is tested for membership in the role linked, or mapped, to the role name.
The security role name specified here is the security role name used in the application code. The value of the role-name element must be the String used as the parameter to the HttpServletRequest.isUserInRole(String role) method. The container uses the mapping of security-role-ref to security-role when determining whether or not the user is authorized to access the requested information.
The security role link specified here contains the value of the name of the security role that the user may be mapped into. The role-link element is used to link a security role reference to a defined security role. The role-link element must contain the name of one of the security roles defined in the security-role elements.
For more information about using security-role-ref with the isUserInRole method, read Declaring and Linking Role References.
If you read Working with Realms, Users, Groups, and Roles, you will remember the following information:
On the Enterprise Server, the following concepts need to be understood in order to work with security roles.
A realm is a complete database of users and groups that identify valid users of a web application (or a set of web applications) and are controlled by the same authentication policy. For more information, read What Is a Realm?.
A user is an individual (or application program) identity that has been defined in the Enterprise Server. On the Enterprise Server, a user generally has a user name, a password, and, optionally, a list of groups to which this user has been assigned. For more information, read What Is a User?.
A group is a set of authenticated users, classified by common traits, defined in the Enterprise Server. For more information, read What Is a Group?.
A principal is an entity that can be authenticated by an authentication protocol in a security service that is deployed in an enterprise.
For more information on configuring users on the Enterprise Server, read Managing Users and Groups on the Enterprise Server.
During deployment, the deployer takes the information provided in the application deployment descriptor and maps the roles specified for the application to users and groups defined on the server using the Enterprise Server deployment descriptors sun-web.xml, sun-ejb-jar.xml, or sun-application.xml.
For more information, read Mapping Security Roles to Enterprise Server Groups.
The concepts of users, groups, principals, and realms exist in most application or web servers, but might use different names in different products. If you are using a server other than Enterprise Server, consult your product's documentation for the terminology specific to that server.
You can declare security role names used in web applications using the security-role element of the deployment descriptor. Use this element to list all of the security roles that you have referenced in your application, and also in conjunction with the security-role-ref element (see Declaring and Linking Role References.)
The following snippet of a deployment descriptor is taken from the simple sample application. This snippet declares the roles that will be used in the application using the security-role element, and specifies which of these roles is authorized to access protected resources using the auth-constraint element.
<security-constraint> <web-resource-collection> <web-resource-name>Protected Area</web-resource-name> <url-pattern>/jsp/security/protected/*</url-pattern> <http-method>PUT</http-method> <http-method>DELETE</http-method> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>manager</role-name> </auth-constraint> </security-constraint> <!-- Security roles used by this web application --> <security-role> <role-name>manager</role-name> </security-role> <security-role> <role-name>employee</role-name> </security-role>
In this example, the security-role element lists all of the security roles used in the application: manager and employee. This enables the deployer to map all of the roles defined in the application to users and groups defined on the Enterprise Server.
The auth-constraint element specifies the role, manager, that can access the HTTP methods PUT, DELETE, GET, POST located in the directory specified by the url-pattern element (/jsp/security/protected/*).
To map security roles defined in applications to Enterprise Server principals and groups, use the security-role-mapping element in the runtime deployment descriptor (DD). The runtime deployment descriptor is different from the application deployment descriptor file. The runtime deployment descriptor is an XML file that contains information such as the context root of the web application and the mapping of the portable names of an application’s resources to the Enterprise Server resources. The Enterprise Server web application runtime DD is located in the /WEB-INF/ directory along with the web application deployment descriptor. Runtime deployment descriptors are named sun-web.xml, sun-application.xml, or sun-ejb-jar.xml.
The following example demonstrates how to do this mapping in the sun-web.xml file, which is the file used for web applications:
<sun-web-app> <security-role-mapping> <role-name>CEO</role-name> <principal-name>Schwartz</principal-name> </security-role-mapping> <security-role-mapping> <role-name>Admin</role-name> <group-name>director</group-name> </security-role-mapping> ... </sun-web-app>
A role can be mapped to specific principals, specific groups, or both. The principal or group names must be valid principals or groups in the current default realm, or in the realm specified in the login-config element. In this example, the role of CEO that is used in the application is mapped to a principal named Schwartz that exists on the application server. Mapping a role to a specific principal is useful when the person occupying that role may change. For this application, you would only need to modify the runtime deployment descriptor and not search and replace throughout the application for references to this principal.
Also in this example, the role of Admin is mapped to a group of users who are assigned the group name of director. This is useful because the group of people authorized to access director-level administrative data only has to be maintained on the Enterprise Server. The application developer does not need to know who these people are, just define the group of people who will be given access to the information.
The role-name must match the role-name in the security-role element of the corresponding application deployment descriptor (web.xml, ejb-jar.xml) or the role name defined in an @DeclareRoles annotation.
Sometimes the role names used in the application are the same as the group names defined on the Enterprise Server. Under these circumstances, you can use the Admin Console to define a default principal-to-role-mapping that applies to the entire Enterprise Server instance. From the Admin Console, select Configuration, then Security, then check the Enable box beside Default Principal to Role Mapping. For more information, read the Sun GlassFish Enterprise Server v3 Administration Guide.