Using Security Realms | Pro Apache Tomcat 5/5.5 (Experts Voice in Java)

Recall that a realm is a programming interface that’s used to authenticate users and implement container-managed security based on roles. The actual mapping of users to roles can be specified at deployment time—and can be changed dynamically without having to change the application code. I introduced realms in Chapter 11 but deferred a detailed discussion of the Web application-specific configuration to this chapter.

When protecting a resource, you must know which roles are to have access to it. This information is stored in the Web application’s web.xml file in the <security-constraint> element. The application’s developer should provide you with this information, but it’s a good idea to be familiar with the options that can be used in a Web application.

These settings are usually the developer’s job, and you just have to set up the server appropriately. However, the admin and manager applications are also protected resources, and you’re in sole charge of them and may want to change their configuration.

Adding Settings to web.xml

The <web-resource-collection> element of web.xml is a convenient place to group Web resources together so that security can be applied uniformly. You specify the name of the resource and the URL patterns to cover inside this element, which is a subelement of <security-constraint>.

The <role-name> subelement of <auth-constraint>, itself a subelement of <security-constraint>, specifies a role that’s allowed to access this section of the Web application. Any user belonging to this role may log in, providing they give a valid password. This is the domain of the administrator, as users and roles are defined in realms in server.xml. The Web application doesn’t care what realm is used, as long as the user is configured in one of them.

Listing 12-11 shows the relevant section of the admin application’s web.xml file.

Listing 12-11: The Section of web.xml That Protects a Web Application

 <!-- Security is active on entire directory -->  <security-constraint>    <display-name>      Tomcat Server Configuration Security Constraint    </display-name>    <web-resource-collection>      <web-resource-name>Protected Area</web-resource-name>      <!-- Define the context-relative URL(s) to be protected -->      <url-pattern>*.jsp</url-pattern>      <url-pattern>*.do</url-pattern>      <url-pattern>*.html</url-pattern>    </web-resource-collection>    <auth-constraint>      <!-- Anyone with one of the listed roles may access this area -->      <role-name>admin</role-name>    </auth-constraint>  </security-constraint>

Here three patterns have been covered by the constraint: *.jsp, *.do, and *.html. This means any request for a file matching these patterns will be challenged. Tomcat will then authenticate the user and allow them to view the resource if they have the role specified, which in this case is admin.

Another element in web.xml has an association with realms. This is the <login-config> element that specifies how Tomcat challenges a user when they request a resource. Listing 12-12 shows the admin application’s entry.

Listing 12-12: The Section of web.xml That Specifies a Login Mechanism

 <!-- Login configuration uses form-based authentication -->  <login-config>    <auth-method>FORM</auth-method>    <realm-name>      Tomcat Server Configuration Form-Based Authentication Area    </realm-name>    <form-login-config>      <form-login-page>/login.jsp</form-login-page>      <form-error-page>/error.jsp</form-error-page>    </form-login-config>  </login-config>

<login-config> sets the type of login and authentication that the application needs. In this case, the application has form-based authentication, which means Tomcat will use the form page specified instead of the user’s browser. This may also be BASIC, DIGEST, or CLIENT-CERT.

Choosing Form-Based Authentication

Form-based authentication is a good option for a few reasons.

The server handles the user information. In the other forms of authentication, the browser may cache the authentication information. While this is convenient for the user, it isn’t as secure as the server holding the information.
BASIC authentication is easy to decode because the user information is sent as a plain, base64-encoded string.
Not all browsers supported DIGEST authentication, so you can’t guarantee that all clients will be able to authenticate. However, if the application is in a closed environment, such as a corporate intranet, it’s easier to control the choice of browser. Internet Explorer, Mozilla, Firefox, and Konqueror all support DIGEST authentication.
DIGEST authentication doesn’t work if the passwords are digested on the Tomcat side because of the way that the DIGEST mechanism calculates its digest. The browser first calculates a digest of the username, the password, the URL, the HTTP method, and a random string sent to it by the server. Likewise, the server creates a digest using the same information and then compares the two digests. However, as the password is already digested on the server, and thus different from the version entered into the browser, the two digests will be different and authentication will fail. In other words, Tomcat is creating a message digest of a message digest.
JDBC realms don’t currently work with DIGEST authentication. Some of the algorithms to digest the password from the database aren’t yet implemented.
CLIENT-AUTH is really necessary only in business-to-business transactions, so it doesn’t appear in most Web applications that you’ll see.

The one drawback of form-based login for the manager application is that you can’t run manager commands with Ant because it can authenticate only using BASIC authentication.

Using Custom Login and Error Pages

If you want to add form-based authentication to a Web application in place of some other type supplied by the developers, Listing 12-13 shows an example.

Listing 12-13: An Example Form for Login

 <%@ taglib prefix="c" uri="http://java.sun.com/jstl/core_rt" %>  <c:url value="j_security_check" var="j_security_check"/>  <html>    <head><title>Please Log In</title>    <body>      <form method="POST"            action='${j_security_check}' >        <table border="0" cellspacing="5">          <tr>            <th align="right">Username:</th>            <td align="left"><input type="text" name="j_username"></td>          </tr>          <tr>            <th align="right">Password:</th>            <td align="left"><input type="password" name="j_password"></td>          </tr>          <tr>            <td align="right"><input type="submit" value="Log In"></td>            <td align="left"><input type="reset"></td>          </tr>        </table>      </form>    </body>  </html>

The important values here are j_security_check, j_username, and j_password. Your form must submit to the special j_security_check URL (here encoded using the core JSTL tag library to allow for browsers that don’t use cookies), with the two special parameter names. This URL is part of the authentication mechanism and will authenticate the user.

Listing 12-14 shows an example error page that’s displayed to users if they fail to log in correctly, though you could quite easily use the original page.

Listing 12-14: A Login Error Page

 <%@ taglib prefix="c" uri="http://java.sun.com/jstl/core_rt" %>  <c:url value="ch12/login.jsp" var="login"/>  <html>    <head><title>Error: Login Failure</title></head>    <body>      Login failed, please try      <a href='${login}'>again</a>.    </body>  </html>

This is simple and gives a link for the user to return to the login page following a failure.

Place these files in a Web application, and update the links appropriately. The following examples will assume you’ve placed them in tomcatBook/ch12. Listing 12-15 shows the web.xml entry to protect the entire Web application.

Listing 12-15: An Example web.xml Entry to Protect the tomcatBook Web Application

 <!-- Define a Security Constraint on this Application -->  <security-constraint>    <web-resource-collection>      <web-resource-name>Tomcat Book Application</web-resource-name>      <url-pattern>/*</url-pattern>    </web-resource-collection>    <auth-constraint>       <role-name>tomcat</role-name>    </auth-constraint>  </security-constraint>  <!-- Define the Login Configuration for this Application -->  <login-config>    <auth-method>FORM</auth-method>    <realm-name>Tomcat Book Application</realm-name>    <form-login-config>      <form-login-page>/ch12/login.jsp</form-login-page>      <form-error-page>/ch12/error.jsp</form-error-page>    </form-login-config>  </login-config>  <!-- Security roles referenced by this Web application -->  <security-role>    <description>      The role that's required to log in to the Tomcat Book Application    </description>    <role-name>tomcat</role-name>  </security-role>

Now whenever you try to access a page in the tomcatBook application for the first time, you’ll have to enter user details in the ch12/login.jsp page. If you provide the wrong details or have the wrong role, then you’ll see the ch12/error.jsp page. This security constraint will use whichever realm you’ve configured (see Chapter 11 for details of configuring realms).