CPSC 371 Lab, 24 October 2003
Server-Managed Security

In this lab, you will get started for real on your term project. Over the course of the rest of the term, you will be developing a Web application with a variety of features. One of the required features is that the application should have a user database, and there should be access restrictions to parts of the application, based on user roles. In Part 1 of the lab, you will create your application directory, set up your user database, and make sure that access restrictions are working. In Part 2, you will create a Web interface for managing the user database.

Parts 1 and 2 of the lab are due in class next Friday. I will ask you to demonstrate during next Friday's lab that you have finished the lab. You should also turn in a printout of the work you do for Part 2.

Part 1: Users and Authorization

First, it's time to begin the actual application development. That is, you should choose a name for the application and create a directory of the same name in the Tomcat webapps folder. Also create a WEB-INF subdirectory and a classes sub-directory of WEB-INF. For now, you can copy some existing Web pages and/or servlets into the new application directory for testing purposes. (You can delete them later, unless you want them to become part of your term project.) You might want to copy the pages you wrote for the previous lab.

Next, you will want to configure some access restrictions in a web.xml file in the WEB-INF directory. This is discussed in Murach, but the syntax is not something that you should memorize. Here is a sample web.xml file that does access control, including some XML comments on the important parts:

   <?xml version="1.0" encoding="ISO-8859-1"?>

   <!DOCTYPE web-app
       PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"



        <web-resource-collection>     <!-- Defines a section of the web site -->
              Adminstration           <!-- arbitray name, not used elsewhere -->
           <url-pattern>/*</url-pattern>  <!-- This actually defines which
                                               URL's are included.  /* means
                                               the whole site.  /dirname/* would
                                               be everything in a directory
                                               named dirname.  /admin.jsp
                                               woudl be a single page.
                                               /servlet/* would be all
                                               servlets.  You can have more than
                                               one url-pattern element. -->

           <role-name>tomcat</role-name>  <!-- Users who are assigned the
                                               role named "tomcat" will have
                                               access.  You can list more
                                               than one role-name.  --> 


     <login-config>  <!-- How should users log in? With BASIC, the
                          browser pops up a window.  The realm-name 
                          is displayed to the user in the login box. -->
        <realm-name>Bedrock Bulletin Board</realm-name>


You can cut-and-paste this from a Web browser into your own file. Before modifying the file, start your server and try to access one of the pages in your application. You should get a login box, and you should be able to log in with username tomcat and password tomcat. This works because the Tomcat server is using its default user database, which is defined in the file tomcat_users.xml in the conf directory. This file defines a user with username=tomcat, password=tomcat, and role=tomcat. (The role is mentioned in the <role-name> tag in web.xml.)

You will want to change several of the items in the web.xml file to match your plan for your web application. At some point in the future, you might want to come back and implement FORM login instead of BASIC, but I advise leaving it set to BASIC for now.

You are going to use a database for user data. You need to create the database, and you need to configure Tomcat to use the database.

You are going to need at least one database for your Web application. You can use the database that you created last week, if you are satisfied with the name, or you can create a new one using the same procedure. You need two user tables, one to store username/password data and one to store username/role data. It would be easiest to create these using the same names that are used in Murach, since they match the Tomcat defaults. You can add extra columns to the tables if you need them, without causing any problems. I suggest having a numeric user id, for example. Here's a pair of possible CREATE TABLE commands; the "UNIQUE INDEX" specifies that you can't have two rows with the same user name:

    CREATE TABLE users (
       user_id int AUTO_INCREMENT PRIMARY KEY,
       user_name VARCHAR(16) NOT NULL,
       user_pass VARCHAR(16) NOT NULL,
       UNIQUE INDEX(user_name)
    CREATE TABLE user_roles (
       user_name VARCHAR(16) NOT NULL,
       role_name VARCHAR(16) NOT NULL,

You should create and least one user and assign that user a role by inserting appropriate values in the two tables.

Finally, you should edit the server.xml file in the conf directory to use your user database. This is discussed in Murach. You have to find and edit the part of server.xml that says:

      <Realm className="org.apache.catalina.realm.MemoryRealm" />

      <!-- Replace the above Realm with one of the following to get a Realm
           stored in a database and accessed via JDBC -->

      <Realm  className="org.apache.catalina.realm.JDBCRealm" debug="99"
              userTable="users" userNameCol="user_name" userCredCol="user_pass"
          userRoleTable="user_roles" roleNameCol="role_name" />

Error in server.xml??? It seems like the syntax for a connectionURL has changed since the server.xml file was created. The format given here does not seem to work. The semicolon before "password" should actually be an ampersand. Because this is XML, the ampersand should be written as &amp;. That is, the line should read:


In addition to correcting this error, you also have to comment out (or remove) the first line shown here, and remove the commenting around the next <Realm> tag. If you used the default names in your database tables, the only thing you have to change is the connectionURL line. Replace "authority" with your database name. Replace username "test" and password "test" with the MySQL username and password that are to be used to access your database. Replace "localhost" if the MySQL server is on a different computer from the one where Tomcat is running. And that's it!

You will have to restart the server for the change to take effect. Make sure you run it using the command catalina.sh run so that you can see any error messages in the command window when it starts. If it's working, you should be able to log into your application using the user that you entered into the database. (If not, did you remember to change the <role-name> in web.xml?)

Part 2: User Management System

To make things easy on yourself as the administrator of your Web application, it's nice to have a web page that can be used to add new users. You might also want to provide the capability of deleting users and assigning roles to users. This is a "User Management System" for your Web application. Having a Web interface will be much easier than managing the user database by typing in SQL commands by hand. So, create a user management page for your application. The only required feature is that you must be able to create a new user, with a specified password. This is very easy. You can make a more elaborate system if you need it for your project.

Of course, you don't want just anyone to have access to the user management page! Add a new <security-constraint> to the web.xml file that will grant access to the user management system only to appropriate users (for example, to users with the admin role).

David Eck