You want to design your own form to receive the user 's name and password during BASIC authentication.
Use the login-config element in the deployment descriptor and give its nested auth-method element a value of "FORM".
The servlet API offers an alternative to using plain- vanilla BASIC authentication: form-based authentication . This method allows you to design your own form for receiving the user's name and password, as well as specifying the informative page that the servers send to the client if the user's authentication fails. This gives you the ability to provide a much more friendly and customized user interface for applications involving BASIC authentication.
Example 15-5 shows the form-based setup for the web application's deployment descriptor. It differs from Recipe 15.3s setup in one area: the login-config element, which is emphasized in the following code sample.
Example 15-5. The web.xml elements designed for form-based authentication
<!-- 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>FORM</auth-method> <form-login-config> <form-login-page>/login.html</form-login-page> <form-error-page>/loginError.jsp</form-error-page> </form-login-config> </login-config> <security-role> <role-name>dbadmin</role-name> </security-role> <!-- Rest of web.xml deployment descriptor -->
The auth-method element includes the text "FORM". The form-login-config element specifies the login ( /login.html ) and authentication failure page ( /loginError.html ) that your application uses. The forward slash ( / ) preceding the filenames means to navigate to the page from the web application's root directory.
Almost by magic, if a user requests a protected resource in your application, the server sends him the login.html page (in this example) instead of initiating the typical behavior in which the browser displays its own dialog window. If the name and password the user enters turns out to be incorrect, the server routes his request to the loginError.html page.
Example 15-6 shows the login.html page, for reference.
Example 15-6. The login form
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>Welcome</title> </head> <body bgcolor="#ffffff"> <h2>Please Login to the Application</h2> <form method="POST" action="j_security_check"> <table border="0"><tr> <td>Enter the username: </td><td> <input type="text" name="j_username" size="15"> </td> </tr> <tr> <td>Enter the password: </td><td> <input type="password" name="j_password" size="15"> </td> </tr> <tr> <td> <input type="submit" value="Submit"> </td> </tr> </table> </form> </body> </html>
Figure 15-3 shows what this form looks like in a web browser.
Figure 15-3. A form for use with form-based authentication
With form-based authentication, the form tag's action attribute must have the value "j_security_check". The input elements for the username and password must specify the values "j_user_name" and "j_password", respectively, for their name attributes.
Figure 15-4 shows the HTML page that the server sends the user if her authentication fails.
Figure 15-4. Form-based authentication allows the inclusion of your own login-failure page
Example 15-7 shows the source for this page. The form-based approach is more predictable and friendlier than the various browsers' methods for dealing with BASIC authentication.
Example 15-7. The server displays the loginError.jsp page when authentication fails
<html> <head> <title>Login Error</title> </head> <body bgcolor="#ffffff"> <h2>We Apologize, A Login Error Occurred</h2> Please click <a href="http://localhost:8080/home/sqlJsp.jsp">here</a> for another try. <%-- Or, dynamically list hyperlinks to your protected resources here, perhaps by getting them from a database or configuration file, instead of hard-coding a link into the error page. --%> </body> </html>
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.