test

The Java EE 6 Tutorial, Volume I

Introduction to Web Application Deployment Descriptors

The web application deployment descriptor file does pretty much what it's name says it does: it describes how the web application should be deployed. The web application deployment descriptor describes a lot more about a web application than just its security information, but this chapter only discusses the elements of the application deployment descriptor that relate to security.

For web applications written using the Java programming language, the web application deployment descriptor is written using the EXtensible Markup Language (XML) syntax. The web application deployment descriptor is named web.xml, and, when included with a web application, it must reside in a WEB-INF subdirectory at the web application root. The contents of this file direct a deployment tool to deploy a module or application with the specified security settings, and describes other specific configuration requirements and/or container options.

The following XML code is an example of the elements in a deployment descriptor that apply specifically to declaring security for web applications or for resources within web applications. This example comes from An Example of Security, from the Java Servlet Specification, Version 3.0.

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
		http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd"
		version=?2.5?>

		<display-name>A Secure Application</display-name>
		<servlet>
			<servlet-name>catalog</servlet-name>
			<servlet-class>com.mycorp.CatalogServlet</servlet-class>
			<init-param>
				<param-name>catalog</param-name>
				<param-value>Spring</param-value>
			</init-param>

			<!-- Defining Security Roles -->

			<security-role-ref>
				<role-name>MGR</role-name>
				<!-- role name used in code -->
				<role-link>manager</role-link>
			</security-role-ref>
		</servlet>
		<security-role>
			<role-name>manager</role-name>
		</security-role>
		<servlet-mapping>
			<servlet-name>catalog</servlet-name>
			<url-pattern>/catalog/*</url-pattern>
		</servlet-mapping>

		<!-- Defining A Security Constraint -->

		<security-constraint>
			<!-- Specifying the Resources to be Protected -->

			<web-resource-collection>
				<web-resource-name>SalesInfo</web-resource-name>
				<url-pattern>/salesinfo/*</url-pattern>
				<http-method>GET</http-method>
				<http-method>POST</http-method>
			</web-resource-collection>
			<!-- Specifying which Users Can Access Protected Resources -->

			<auth-constraint>
				<role-name>manager</role-name>
			</auth-constraint>
			<!-- Specifying Secure Transport using SSL  -->

			<user-data-constraint>
				<transport-guarantee>CONFIDENTIAL	</transport-guarantee>
			</user-data-constraint>
		</security-constraint>

		<!-- Specifying an Authentication Method -->
		<login-config>
			<auth-method>BASIC</auth-method>
			<realm-name>file</realm-name>
		</login-config>
</web-app>

Even if you are simply using the deployment descriptor to specify security, there are some structural elements that must be included in this file in order for it to work properly. For example, the <security-constraint> element is a sub-element of the <web-app> element, so the <web-app> element must always be included, and it must indicate the version of the web application schema (2.4 or 2.5) it is using. The elements that are specified within the deployment descriptor must comply with the rules for processing that version of the deployment descriptor. Version 3.0 of the Java Servlet Specification, which can be downloaded at http://jcp.org/en/jsr/detail?id=315, contains more information regarding the structure of deployment descriptors.

XML files are hierarchical. The elements must be specified in a particular order within the deployment descriptor, between elements that are its parent. To visually see an example of how the deployment descriptor elements are nested within their parent elements, refer to the elements within the <security-constraint> element above, which is itself nested within <web-app> elements. For this example, the lines have been indented to emphasize the nesting aspect of the file, but the file itself ignores the formatting and relies only on the elements and their content for its processing. Information about the application is specified as a value between the opening (<element-name>) and closing (</element-name>) elements. For example, between the opening <transport-guarantee> element and the closing </transport-guarantee> element, there is the value CONFIDENTIAL, which describes which type of transport guarantee should be used for this application.

The following sections describe each of the security elements of a deployment descriptor in more detail, listing all of the options available for each element:

Some of the elements of web application security must be addressed in server configuration files rather than in the deployment descriptor or annotations for the web application. Configuring security on the Enterprise Server is discussed in the following sections and books: