BASIC Authentication

HTTP has a built-in authentication protocol. When you log in to a page that requires authentication, the Web server first sends back a message telling the browser to send authentication information. The browser then prompts you for a username and password to send to the server. After the browser sends the username and password (assuming they are correct), the Web server displays the requested page. The browser holds on to the authentication information in case the Web server asks for it again.

To set up BASIC authentication for a Web application, you must add several new tags to your web.xml file. Listing 23.2 shows a basic web.xml file that uses authentication.

Listing 23.2 Source Code for web.xml for the authtest Application

<?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_4.xsd"
    version="2.4">
    <display-name>authtest</display-name>
    <description>A test of authentication</description>
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>SecureTest</web-resource-name>
            <url-pattern>/*</url-pattern>
            <http-method>GET</http-method>
            <http-method>POST</http-method>
        </web-resource-collection>
        <user-data-constraint>
            <description>SSL not required</description>
            <transport-guarantee>NONE</transport-guarantee>
        </user-data-constraint>
        <auth-constraint>
            <description>Let only managers use this app</description>
            <role-name>manager</role-name>
        </auth-constraint>
    </security-constraint>
    <security-role>
        <description>The role of manager is one that can use our application.
        </description>
        <role-name>manager</role-name>
    </security-role>
    <login-config>
        <auth-method>BASIC</auth-method>
    </login-config>
</web-app>

The main tags that have been added to the basic deployment descriptor are <security-constraint>, <login-config>, and <security-role>.

The <security-constraint> Tag

The <security-constraint> tag tells the servlet engine what security requirements your application has. You can have more than one security constraint if necessary. Within the security constraint, you must specify a Web resource collection with the <web-resource-collection> tag.

A Web resource collection is a collection of URL patterns to which the security constraint applies. For instance, you might want to restrict only a single directory in your application. The <url-pattern> tag in your resource collection would then contain a pattern matching the directory you want to restrict. The pattern /* in Listing 23.1 means that the security constraint applies to all URLs in the application's directory. The <web-resource-name> tag specifies the name for the Web resource collection. There is no connection between the name and any of the URLs within it. The name serves little purpose but can be useful for various development and configuration tools.

The other tag you find in the Web resource collection is the <http-method> tag. This specifies which HTTP methods require authentication. If you do not specify an HTTP method, the security applies to all HTTP methods. You might, for example, want to perform authentication for an HTTP POST but not for a GET. You might also want to perform different kinds of authentication for GET and POST. In the latter case, you specify two separate security constraints, one with an HTTP method of GET and the other with an HTTP method of POST. You can also use authentication with other HTTP methods such as PUT and DELETE.

The <user-data-constraint> tag tells the servlet engine what kind of data security your application needs. You can include a <description> tag to describe the constraint, but it is optional. The <transport-guarantee> tag indicates the kind of transport-level data security your application needs. The value for the <transport-guarantee> tag can be one of three values:

• NONE— Indicates that the application doesn't require any special data security.

• INTEGRAL— Indicates that the client and server should ensure that the data can't be changed by anyone. Although you would typically use an encrypted protocol such as SSL for this level of security, INTEGRAL does not require that the data can't be observed by a third party. You could send digitally signed, unencrypted messages back and forth and still meet the requirements for INTEGRAL.

• CONFIDENTIAL— Requires that a third party can't tamper with the data or read it. You will almost always use SSL for this level unless you have another encryption transport protocol available.

The <auth-constraint> tag enables you to specify the various roles to which this security constraint applies. The <role-name> tag enables you to specify a specific role. You can include multiple <role-name> tags within a single <auth-constraint> tag.

The <login-config> Tag

The <login-config> tag enables you to control the type of authentication you want the servlet engine and browser to perform. You specify the type of authentication through the <auth-method> tag. The servlet specification supports four kinds of authentication methods:

• BASIC— Causes the browser to prompt the user for a username and password and then send them to the server without encrypting them first. If you use BASIC authentication over an SSL (encrypted) connection, the username and password are encrypted by the SSL protocol itself. The password is encoded using Base64 encoding, which isn't really a form of encryption.

• DIGEST— Causes the browser to encrypt the password before sending it. Although this method can prevent someone from reading the password as it travels over the network, this method is not as secure as using a fully encrypted session.

• FORM— Just like the BASIC authentication method, except the server sends back a login form rather than using the browser's built-in form. The username and password are transmitted as form variables.

• CLIENT-CERT— Requires the user to provide a public key certificate for authentication. This method is frequently too cumbersome for general users because they rarely have their own digital certificates, but it does offer a reasonably high level of security, even over an unencrypted connection.

For BASIC authentication, you can specify a realm name using the <realm-name> tag. The realms help organize various sections of a Web site that might need authentication. By grouping applications into separate realms, you can require the user to log in to each application. The realm name isn't configured anywhere other than in the <realm-name> tag, so you don't need to worry about setting up different realms. A realm is basically a grouping of usernames and passwords. You can have multiple sets of users, each belonging to a different realm. For example, you might have a set of personnel Web applications with users belonging to a "manager" realm. Likewise, you might have an administration Web application with users that belong to an "admin" realm. In addition to usernames and passwords, you can define various roles for users. You can restrict parts of a Web application based on the role of a user (a user might belong to a "power-user" role or a "sysadmin" role). By granting access based on a role rather than an individual user, you can grant and revoke privileges to whole sets of users with a single operation.

Listing 23.1 uses BASIC authentication. Figure 23.1 shows the login prompt for a page in the authtest application.

The <security-role> Tag

The <security-role> identifies the roles that participate in an application. In this simple example, we've defined only one—manager. More-sophisticated applications will have several. It's important to note that the container is responsible for associating users and roles. As mentioned earlier, that means that you have to edit tomcat-users.xml, which is located off of Tomcat's home directory in conf. The format of that file is self-explanatory.