Web-Tier Security

The following sections address protecting resources and authenticating users in the Web tier.

Your Web application is defined using a standard web.xml deployment descriptor. The deployment descriptor must indicate which version of the web application schema (2.2, 2.3, or 2.4) it is using, and the elements specified within the deployment descriptor must comply with the rules for processing that version of the deployment descriptor. For version 2.4 of the Java Servlet Specification, this is "SRV.13.3, Rules for Processing the Deployment Descriptor". These specifications may be downloaded from http://java.sun.com/products/servlet/download.html. For more information on deployment descriptors, see Chapter 4.

The deployment descriptor is used to convey the elements and configuration information of a Web application. Security in a Web application is configured using the following elements of the deployment descriptor:

<login-config>

The <login-config> element specifies how the user is prompted to login in. If this element is present, the user must be authenticated before it can access any resource that is constrained by a <security-constraint>. The <login-config> element is discussed in Configuring Login Authentication.

<security-constraint>

The <security-constraint> element is used to define the access privileges to a collection of resources using their URL mapping. Security constraints are discussed in Controlling Access to Web Resources.

<security-role>

The <security-role> element represents a defined group for the realm. Security roles are discussed in Security Roles.

These elements of the deployment descriptor may be entered directly into the web.xml file.

Protecting Web Resources

You can protect Web resources by specifying a security constraint. A security constraint determines who is authorized to access a Web resource collection, a list of URL patterns and HTTP methods that describe a set of resources to be protected. Security constraints can be defined using a deployment descriptor, as discussed in Controlling Access to Web Resources.

If you try to access a protected Web resource as an unauthenticated user, the Web container will try to authenticate you. The container will only accept the request after you have proven your identity to the container and have been granted permission to access the resource.

Security constraints only work on the original request URI, not on calls made via a RequestDispatcher (which include <jsp:include> and <jsp:forward>). Inside the application, it is assumed that the application itself has complete access to all resources and would not forward a user request unless it had decided that the requesting user had access also.

Controlling Access to Web Resources

You can set up a security constraint by coding the information directly into the deployment descriptor between <security-constraint></security-constraint> tags. When you define security constraints, you need to make sure you have addressed the following issues:

Set up login authentication (discussed in Configuring Login Authentication).

Add a security constraint.

Add a web resource collection.

Define and include an authorized security role (discussed in Security Roles).

Identify URL patterns to constrain.

Identify HTTP methods to constrain (POST, GET).

Specify whether there are any guarantees on how the data will be transported between client and server (NONE, INTEGRAL, CONFIDENTIAL).

If, for example, we were to look at the security portion of the deployment descriptor for a simple application, the web.xml file might look something like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
  PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 
    2.3//EN"
  "http://java.sun.com./dtd/web-app_2_3.dtd">

...

  <display-name>SimpleApp</display-name>
  <servlet>
    <servlet-name>index</servlet-name>
    <display-name>index</display-name>
    <jsp-file>/index.jsp</jsp-file>
    <!-- SECURITY-ROLE-REF -->
    <security-role-ref>
      <role-name>SimpleAppCustomer</role-name>
      <role-link>customer</role-link>
    </security-role-ref>
  </servlet>
  <session-config>
    <session-timeout>30</session-timeout>
  </session-config>

  <!-- SECURITY CONSTRAINT -->
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>WRCollection</web-resource-name>
      <url-pattern>/index.jsp</url-pattern>
      <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
      <role-name>customer</role-name>
    </auth-constraint>
    <user-data-constraint>
      <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
  </security-constraint>

  <!-- LOGIN AUTHENTICATION -->
  <login-config>
    <realm-name></realm-name>
    <auth-method>BASIC</auth-method>
  </login-config>
  
  <!-- SECURITY ROLES -->
  <security-role>
    <role-name>admin</role-name>
  </security-role>
  <security-role>
    <description>Simple App Customer</description>
    <role-name>customer</role-name>
  </security-role>
  <security-role>
    <role-name>manager</role-name>
  </security-role>
  <security-role>
    <role-name>provider</role-name>
  </security-role>

...

Authenticating Users of Web Resources

When you try to access a protected Web resource, the Web container activates the authentication mechanism that has been configured for that resource. You can configure the following authentication mechanisms for a Web resource:

None

If you do not specify one of the following methods, the user will not be authenticated.

HTTP Basic authentication

If you specify HTTP basic authentication, (<auth-method>BASIC</auth-method>), the Web server will authenticate a user by using the user name and password obtained from the Web client.

Form-based authentication

If you specify form-based authentication (<auth-method>FORM</auth-method>), you can customize the login screen and error pages that are presented to the end user by an HTTP browser.

Neither form-based authentication nor HTTP basic authentication is particularly secure. In form-based authentication, the content of the user dialog is sent as plain text, and the target server is not authenticated. Basic authentication sends user names and passwords over the Internet as text that is uu-encoded, but not encrypted. This form of authentication, which uses Base64 encoding, can expose your user names and passwords unless all connections are over SSL. If someone can intercept the transmission, the user name and password information can easily be decoded.

Client-certificate authentication

Client-certificate authentication (<auth-method>CLIENT-CERT</auth-method>) is a more secure method of authentication than either basic or form-based authentication. It uses HTTP over SSL, in which the server and, optionally, the client authenticate each other with Public Key Certificates. Secure Sockets Layer (SSL) provides data encryption, server authentication, message integrity, and optional client authentication for a TCP/IP connection. You can think of a public key certificate as the digital equivalent of a passport. It is issued by a trusted organization, which is called a certificate authority (CA), and provides identification for the bearer. If you specify client-certificate authentication, the Web server will authenticate the client using the client's X.509 certificate, a public key certificate that conforms to a standard that is defined by X.509 Public Key Infrastructure (PKI). Prior to running an application that uses SSL, you must configure SSL support on the server (see Installing and Configuring SSL Support) and set up the public key certificate (see Setting Up Digital Certificates).

Digest authentication

Digested password authentication (<auth-method>DIGEST</auth-method>) supports the concept of digesting user passwords. This causes the stored version of the passwords to be encoded in a form that is not easily reversible, but that the Web server can still utilize for authentication.

From a user perspective, digest authentication acts almost identically to basic authentication in that it triggers a login dialog. The difference between basic and digest authentication is that on the network connection between the browser and the server, the password is encrypted, even on a non-SSL connection. In the server, the password can be stored in clear text or encrypted text, which is true for all login methods and is independent of the choice that the application deployer makes.

Configuring Login Authentication

You can set up login authentication by coding the information directly into the deployment descriptor between <login-config></login-config> tags. When you configure the authentication mechanism that the Web resources in a WAR will use, you have the following options:

Specify one of the user authentication methods described in Authenticating Users of Web Resources.

Specify a security realm. If omitted, the default realm is assumed.

If the authentication method is specified as FORM, specify a form login page and form error page.

The form login page defines the location of the form that will be used to authenticate the user. The form error page is the resource that responds to a failed authentication.

The following sample code shows a section of a deployment descriptor that uses form-based login authentication. The <form-login-page> element provides the URI of a Web resource relative to the document root that will be used to authenticate the user. The login page can be an HTML page, a JSP page, or a servlet, and must return an HTML page containing a form that conforms to specific naming conventions (see the relevant Servlet specification for more information on these requirements). The <form-error-page> element requires a URI of a Web resource relative to the document root that send a response when authentication has failed.

A Universal Resource Identifier (URI), is a globally unique identifier for a resource. A Universal Resource Locator (URL) is a kind of URI that specifies the retrieval protocol (http or https for Web applications) and physical location of a resource (host name and host-relative path).

In the Java Servlet specification, the request URI is the part of a URL after the host name and port. For example, in the URL http://localhost:8080/myApp/jsp/hello.jsp, the request URI would be /jsp/hello.jsp. The request URI is further subdivided into the context path (which decides which Web application should process the request) and the rest of the path that is used to select the target servlet.

Using SSL to Enhance the Confidentiality of HTTP Basic and Form-Based Authentication

Passwords are not protected for confidentiality with HTTP basic or form-based authentication, meaning that passwords sent between a client and a server on a non-protected session can be viewed and intercepted by third parties. To overcome this limitation, you can run these authentication protocols over an SSL-protected session and ensure that all message content is protected for confidentiality.

If the default configuration of your Web server does not support SSL, you must configure it with an SSL connector to make this work. The default configuration of the Tomcat server does not include an SSL Connector. To configure Tomcat for SSL, follow the instructions in Installing and Configuring SSL Support.

To configure HTTP basic or form-based authentication over SSL, specify CONFIDENTIAL or INTEGRAL as the user authentication method within the <transport-guarantee> elements. Specify CONFIDENTIAL when the application requires that data be transmitted so as to prevent other entities from observing the contents of the transmission. Specify INTEGRAL when the application requires that the data be sent between client and server in such a way that it cannot be changed in transit. The following example code from a web.xml file shows this setting in context:

If you specify CONFIDENTIAL or INTEGRAL as a security constraint, that type of security constraint applies to all requests that match the URL patterns in the Web resource collection, not just to the login dialog.

Note: Good Security Practice: If you are using sessions, once you switch to SSL you should never accept any further requests for that session that are non-SSL. For example, a shopping site might not use SSL until the checkout page, then it may switch to using SSL in order to accept your card number. After switching to SSL, you should stop listening to non-SSL requests for this session. The reason for this practice is that the session ID itself was non-encrypted on the earlier communications, which is not so bad when you're just doing your shopping, but once the credit card information is stored in the session, you don't want a bad guy trying to fake the purchase transaction against your credit card. This practice could be easily implemented using a filter.

Using Programmatic Security in the Web Tier

Programmatic security is used by security-aware applications when declarative security alone is not sufficient to express the security model of the application. Programmatic security consists of the following methods of the HttpServletRequest interface:

getRemoteUser - used to determine the user name with which the client authenticated.

isUserInRole - used to determine if a user is in a specific security role.

getUserPrincipal - returns a java.security.Principal object.

These APIs allow servlets to make business logic decisions based on the logical role of the remote user. They also allow the servlet to determine the principal name of the current user.

When you use the isUserInRole(String role) method, the String role is mapped to the role name defined in the <role-name> element nested within the <security-role-ref> element of a <servlet> declaration of the web.xml deployment descriptor. The <role-link> element must match a <role-name> defined in the <security-role> element of the web.xml deployment descriptor. If the isUserInRole("admin") method is called within a servlet, the section of example code in bold below would need to be added to ensure security. In this example, the <role-link> parameters are used in the application, the <role-name> element provides some form of abstraction. The applicable sections of the web.xml deployment descriptor would look like this:

As discussed in Security Roles, there also must be a corresponding <role-name> entry in the Web server-specific deployment descriptor, which would look something like this:

Creating the Login Form

The content of the login form in an HTML page, JSP page, or servlet for a login page should be as follows:

Unprotected Web Resources

Many applications feature unprotected Web content, which any caller can access without authentication. In the Web tier, unrestricted access is provided simply by not configuring a security constraint for that particular request URI. It is common to have some unprotected resources and some protected resources. In this case, you will have security constraints and a login method defined, but it will not be used to control access to the unprotected resources. The user won't be asked to log on until the first time they enter a protected request URI.

In the Java Servlet specification, the request URI is the part of a URL after the host name and port. For example, let's say you have an e-commerce site with a browsable catalog you would want anyone to be able to access and a shopping cart area for customers only. You could set up the paths for your Web application so that the pattern /cart/* is protected, but nothing else is protected. Assuming the application is installed at context path /myapp,

http://localhost:8080/myapp/index.jsp is not protected

http://localhost:8080/myapp/cart/index.jsp is protected

A user will not be prompted to log in until the first time that user accesses a resource in the cart subdirectory.