Recipe 15.3 Using BASIC Authentication

Problem

You want to use BASIC authentication with web components in a Tomcat web application.

Solution

Use the security-constraint, login-config, and security-role elements in the deployment descriptor to protect one or more URLs.

Discussion

BASIC authentication is a security method that has been used with web resources for several years, and all popular browsers support it. This method of authentication involves the transfer of usernames and passwords over a network encoded with the Base64 content-encoding mechanism. Base64 is easy to decode and therefore not very secure. The solution is to combine BASIC authentication with SSL, which will further encrypt the data as it is transferred across the network (see Recipe 15.2).

Here is how setting up BASIC authentication works with web applications that you have installed on Tomcat:

When the user requests any of the protected resources, the server sends along a response header that looks like this: WWW-Authenticate: BASIC Realm="MyRealm"

You are probably familiar with what happens next: the browser displays a standard dialog window requesting the client to provide a username and password (Figure 15-1). If the username and password are incorrect, the browser will either give the user another chance to log in by redisplaying the dialog window, or simply send back a server status code "401: Unauthorized" type of response.

The usernames and passwords in the conf/tomcat-users.xml file are case-sensitive. The user has to type them into the dialog window using upper- and lowercase letters exactly as they appear in conf/tomcat-users.xml.

Example 15-4 shows the web.xml elements that are designed to initiate BASIC authentication for the URL pattern /sqlJsp.jsp.

Example 15-4. A security-constraint initiates authentication with a JSP file

<!-- Beginning of web.xml deployment descriptor -->

<security-constraint>

    <web-resource-collection>

        <web-resource-name>JSP database component</web-resource-name>

        <url-pattern>/sqlJsp.jsp</url-pattern>

        <http-method>GET</http-method>
        <http-method>POST</http-method>

    </web-resource-collection>


    <auth-constraint>
        <role-name>dbadmin</role-name>
    </auth-constraint>

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

</security-constraint>

<login-config>
        <auth-method>BASIC</auth-method>
</login-config>
    
<security-role>
    <role-name>dbadmin</role-name>
</security-role>

<!-- Rest of web.xml deployment descriptor -->

The security-constraint element in Example 15-4 contains a web-resource-collection element. This element specifies the following constraints that apply to any requests for /sqlJsp.jsp:

• The constraints apply to any GET or POST requests (as specified by the http-method elements).

• The auth-constraint element nested inside security-constraint contains the role-name dbadmin. Therefore, the requestor must enter the proper username and password (as specified in the tomcat-users.xml file) and be associated with the dbadmin role. Only those who have the dbadmin role can gain access to the protected web resource, even if they enter a proper username and password.

Figure 15-1 shows the dialog box that Netscape 7.1 produces when Tomcat is using BASIC authentication. The URL is used is https://localhost:8443/home/sqlJsp.jsp.

Figure 15-1. A browser dialog window requests a name and password

Notice that the URL uses a secure connection to request the JSP: an HTTPS protocol and port 8443 on Tomcat.

Figure 15-2 shows a browser window after a client has failed authentication.

Figure 15-2. A server status code 401 page as viewed in the web browser

See Also

The Tomcat documentation and Recipe 15.2 on setting up SSL for use with authentication: http://jakarta.apache.org/tomcat/tomcat-4.1-doc/ssl-howto.html; Recipe 3.9 on restricting requests for certain servlets; Recipe 15.5 on logging out a user; Recipe 15.6-Recipe 15.9 on using JAAS.