7.4 Example: BASIC Authentication
In Section 7.2, I showed the external Web site for a fictional company named hot-dot-com.com. In this section, I'll show their intranet. Since applications that use form-based authentication vary only slightly from those that use BASIC authentication, I'll just concentrate on the differences here. I'll start by showing the home page, then list the web.xml file, summarize the various protection mechanisms, show the password file, and give the code for each of the protected resources.
The Home Page
Listing 7.23 shows the top-level home page for the Web application. The application is registered with a URL prefix of /hotdotcom-internal so the home page can be accessed with the URL http://host/hotdotcom-internal/index.jsp as shown in Figure 715. If you've forgotten how to assign URL prefixes to Web applications, review Section 4.1 (Registering Web Applications).
Now, the main home page has no security protections and consequently does not absolutely require an entry in web.xml. However, many users expect URLs that list a directory but no file to invoke the default file from that directory. So, I put a welcome-file-list entry in web.xml (see Listing 7.24 in the next section) to ensure that http://host/hotdotcom-internal/ invokes index.jsp.
Listing 7.23 index.jsp (Top-level home page)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML> <HEAD> <TITLE>hot-dot-com.com!</TITLE> <LINK REL=STYLESHEET HREF="company-styles.css" TYPE="text/css"> </HEAD> <BODY> <TABLE BORDER=5 ALIGN="CENTER"> <TR><TH CLASS="TITLE">hot-dot-com.com!</TABLE> <P> <H3>Welcome to the hot-dot-com intranet</H3> Please select one of the following: <UL> <LI><A HREF="financial-plan.html">Financial Plan</A>. Available to all employees. <LI><A HREF="business-plan.html">Business Plan</A>. Available only to corporate executives. <LI><A HREF="employee-pay.jsp">Employee Compensation Plans</A>. Available to all employees. </UL> </BODY> </HTML>
Figure 715 Home page for the hot-dot-com.com intranet.
The Deployment Descriptor
Listing 7.24 shows the complete deployment descriptor used with the hotdot-com-internal Web application. Again, remember that the order of the sub-elements within the web-app element of web.xml is not arbitraryyou must use the standard ordering. For details, see Section 5.2 (The Order of Elements within the Deployment Descriptor).
The deployment descriptor specifies several things:
URLs that give a directory but no filename result in the server first trying to use index.jsp and next trying index.html. If neither file is available, the result is server specific (e.g., a directory listing).
URLs that use the default servlet mapping (i.e., http://host/hotdotcom/servlet/ServletName) are redirected to the main home page.
The financial-plan.html page can be accessed only by company employees or executives.
The business-plan.html page can be accessed only by company executives.
Listing 7.24 hot-dot-com.com intranet)
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> <web-app> <!-- A servlet that redirects users to the home page. --> <servlet> <servlet-name>Redirector</servlet-name> <servlet-class>hotdotcom.RedirectorServlet</servlet-class> </servlet> <!-- Turn off invoker. Send requests to index.jsp. --> <servlet-mapping> <servlet-name>Redirector</servlet-name> <url-pattern>/servlet/*</url-pattern> </servlet-mapping> <!-- If URL gives a directory but no filename, try index.jsp first and index.html second. If neither is found, the result is server specific (e.g., a directory listing). --> <welcome-file-list> <welcome-file>index.jsp</welcome-file> <welcome-file>index.html</welcome-file> </welcome-file-list> <!-- Protect financial plan. Employees or executives. --> <security-constraint> <web-resource-collection> <web-resource-name>Financial Plan</web-resource-name> <url-pattern>/financial-plan.html</url-pattern> </web-resource-collection> <auth-constraint> <role-name>employee</role-name> <role-name>executive</role-name> </auth-constraint> </security-constraint> <!-- Protect business plan. Executives only. --> <security-constraint> <web-resource-collection> <web-resource-name>Business Plan</web-resource-name> <url-pattern>/business-plan.html</url-pattern> </web-resource-collection> <auth-constraint> <role-name>executive</role-name> </auth-constraint> </security-constraint> <!-- Tell the server to use BASIC authentication. --> <login-config> <auth-method>BASIC</auth-method> <realm-name>Intranet</realm-name> </login-config> </web-app>
The Password File
Password files are not specific to Web applications; they are general to the server. Listing 7.25 shows the password file used by Tomcat for this Web application. It defines three new users: gates and ellison in the employee role and mcnealy in the executive role.
Listing 7.25 install_dir/conf/tomcat-users.xml (Three new users)
<?xml version="1.0" encoding="ISO-8859-1"?> <tomcat-users> <user name="john" password="nhoj" roles="registered-user" /> <user name="jane" password="enaj" roles="registered-user" /> <user name="juan" password="nauj" roles="administrator" /> <user name="juana" password="anauj" roles="administrator,registered-user" /> <user name="gates" password="llib" roles="employee" /> <user name="ellison" password="yrral" roles="employee" /> <user name="mcnealy" password="ttocs" roles="executive" /> </tomcat-users>
The Financial Plan
Listing 7.26 shows the first of the protected pages at the hotdotcom-internal site. Figure 716 shows the dialog box presented by Netscape to unauthenticated users who attempt to access the page. Figure 717 and 718 show unsuccessful and successful login attempts, respectively.
Listing 7.26 financial-plan.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML> <HEAD> <TITLE>Financial Plan</TITLE> <LINK REL=STYLESHEET HREF="company-styles.css" TYPE="text/css"> </HEAD> <BODY> <TABLE BORDER=5 ALIGN="CENTER"> <TR><TH CLASS="TITLE">Financial Plan</TABLE> <P> <H3>Steps:</H3> <OL> <LI>Make lots of money. <LI>Increase value of stock options. <LI>Make more money. <LI>Increase stock option value further. </OL> </BODY> </HTML>
Figure 716 Unauthenticated users who attempt to access protected resources are presented with a dialog box.
Figure 717 A failed login attempt.
Figure 718 A successful login attempt.
The Business Plan
The financial plan of the previous section is available to all employees and executives. The business plan (Listing 7.27), in contrast, is available only to executives. Thus, it is possible for an authenticated user to be denied access to it. Figure 719 shows this result. OK, so you have access to more than one username/password combination. You were authenticated as a user with restricted privileges. You now want to log in as a user with additional privileges. How do you do so? Unfortunately, the answer is: quit the browser and restart. Boo. That's one of the downsides of BASIC authentication.
Figure 720 shows the result after the browser is restarted and the client logs in as a user in the executive role (mcnealy in this case).
Listing 7.27 business-plan.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML> <HEAD> <TITLE>Business Plan</TITLE> <LINK REL=STYLESHEET HREF="company-styles.css" TYPE="text/css"> </HEAD> <BODY> <TABLE BORDER=5 ALIGN="CENTER"> <TR><TH CLASS="TITLE">Business Plan</TABLE> <P> <H3>Steps:</H3> <OL> <LI>Inflate name recognition by buying meaningless ads on high-profile TV shows. <LI>Decrease employee pay by promising stock options instead. <LI>Increase executive pay with lots of perks and bonuses. <LI>Get bought out before anyone notices we have no business plan. </OL> </BODY> </HTML>
Figure 720 Attempt to access the business plan by an authenticated user who is in the executive role.
The Redirector Servlet
As it currently stands, the hotdotcom-internal application has no protected servlets. So, it is not absolutely necessary to disable the invoker servlet and redirect requests that are sent to http://host/hotdotcom-internal/servlet/something. However, it is a good idea to plan ahead and disable the invoker servlet as a matter of course in all Web applications that have restricted resources. This application uses the same redirector servlet (Listing 7.19) and url-pattern entry in web.xml (Listing 7.24) as does the external hotdotcom application.