Configuring Roles in SJSAS
Roles can be configured in the deployment descriptors as follows:
- For applications, security roles are defined in the Java EE application.xml document and roles mappings in the SJSAS sun-application.xml document.
- For web/EJB modules, security roles are defined in the Java EE web.xml or ejb-jar.xml document and roles mapping in the SJSAS sun-web.xml and sun-ejb-jar.xml document.
Following is an example of a security constraint where the role SERVLET-ROLE is authorized to access the GET and POST methods of the SecureServlet.java servlet. <security-constraint> limits access privileges to a set of resources by using their URL mapping. These settings are placed in the web.xml descriptor.
<security-constraint> <web-resource-collection> <web-resource-name>Secure Servlet</web-resource-name> <url-pattern>/SecureServlet</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>SERVLET-ROLE</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint>
The main parts in this fragment are the protected resource URL and the role name. The protected servlet URL is indicated in the <url-pattern>, while the role name is set in the <role-name> element.
If you want to add more methods to SERVLET-ROLE, just add more <http-method> elements (for example, you may want to permit access to PUT and DELETE methods).
Notice that the protected information will travel over a non-protected transport, since the <transport-guarantee> is set to NONE. For a protected transport, you have to set <transport-guarantee> to CONFIDENTIAL and you need to use the SSL protocol (https instead of http) and SSL port. (By default, in SJSAS the SSL port is 8181.)
For JSPs, the situation is similar. For example, following is a security constraint in which the role JSP-ROLE is authorized to access all JSP pages from the /jsps folder.
<security-constraint> <web-resource-collection> <web-resource-name>Secure JSPs</web-resource-name> <url-pattern>/jsps/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>JSP-ROLE</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint>
We also need to define a security role reference, represented by the <security-role-ref> element. It contains the declaration of a security role reference in the web application code. The declaration is mapped in two XML elements (shown in boldface):
<servlet> <servlet-name>SecureServlet</servlet-name> <servlet-class>secure.servlet.SecureServlet</servlet-class> <security-role-ref> <role-name>SERVLET-ROLE-ALIAS</role-name> <role-link>SERVLET-ROLE</role-link> </security-role-ref> </servlet>
The role name indicates the security role name used as an argument to the isUserInRole method (syntax: boolean isUserInRole(String role) ). This method comes from the javax.servlet.http.HttpServletRequest class and it returns a Boolean indicating whether the authenticated user is included in the specified role.
The role link indicates the value of the name of the security role in which the user may be mapped. The name specified here must identify a security role defined in the <security-role> element, which is used in conjunction with the <security-role-ref> element to map roles defined in code to roles defined for the web application. For example, the SERVLET-ROLE and JSP-ROLE should be specified in the <security-role> like this:
<security-role> <role-name>JSP-ROLE</role-name> </security-role>
<security-role> <role-name>SERVLET-ROLE</role-name> </security-role>
Notice that the role name specified in the <role-name> element under <auth-constraint> corresponds to the role name of one of the <security-role> elements defined for this web application, or the specially reserved role name "*".
Putting together these elements (in web.xml), we obtain the deployment descriptor shown in Listing 3.
Listing 3 web.xml.
<?xml version="1.0" encoding="UTF-8"?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<display-name>Roles</display-name>
<servlet> <servlet-name>SecureServlet</servlet-name> <servlet-class>secure.servlet.SecureServlet</servlet-class> <security-role-ref> <role-name>SERVLET-ROLE-ALIAS</role-name> <role-link>SERVLET-ROLE</role-link> </security-role-ref> </servlet> <servlet-mapping> <servlet-name>SecureServlet</servlet-name> <url-pattern>/SecureServlet</url-pattern> </servlet-mapping>
<security-role> <role-name>JSP-ROLE</role-name> </security-role>
<security-role> <role-name>SERVLET-ROLE</role-name> </security-role>
<security-constraint> <web-resource-collection> <web-resource-name>Secure Servlet</web-resource-name> <url-pattern>/SecureServlet</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>SERVLET-ROLE</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint>
<security-constraint> <web-resource-collection> <web-resource-name>Secure JSPs</web-resource-name> <url-pattern>/jsps/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>JSP-ROLE</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint>
<!-- here we will paste the authentication mechanism -->
<welcome-file-list> <welcome-file>index.jsp</welcome-file> </welcome-file-list>
</web-app>
Mapping Roles to Users and Groups
So far, we've configured in web.xml two protected resources (a servlet and a JSP page) and two corresponding roles, but we don't know anything yet about the users or groups of users. The reason is simple: Roles are defined in the application, whereas users and groups are defined in the runtime realm (on the server). The bridge between them is provided by an internal mechanism that maps roles to users and groups. To enable this mechanism, we have to provide a declarative mapping in the sun-application.xml, sun-web.xml, or sun-ejb-jar.xml document. The idea is to map the security roles used in the application and one or more groups/principals defined in a realm of the application server. In Listing 4, we have provided this mapping in the sun-web.xml document.
Listing 4 sun-web.xml.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 9.0 Servlet 2.5//EN" "http://www.sun.com/software/appserver/dtds/sun-web-app_2_5-0.dtd"> <sun-web-app error-url=""> <context-root>/SecurityContext</context-root> <class-loader delegate="true"/> <security-role-mapping> <role-name>SERVLET-ROLE</role-name> <group-name>SERVLET-USERS</group-name> </security-role-mapping> <security-role-mapping> <role-name>JSP-ROLE</role-name> <group-name>JSP-USERS</group-name> </security-role-mapping> </sun-web-app>