Authentication

Tomcat supports authentication as described in the servlet specification. Of course, the specification doesn't describe how you define the allowable users and passwords for authentication. Tomcat provides a flexible mechanism for defining security realms. Realms can be thought of as places to store usernames, passwords, and other items related to security. They also provide the means to authenticate users. Tomcat realms allow you to store username/password combinations in a database, a JNDI server, or a simple text file. You can also write your own custom realm implementations if you need to store your authentication information some other way.

To configure a realm, you add a <Realm> element to the server.xml file in Tomcat's conf directory. The <Realm> element must specify the classname of the realm implementation (the class that actually handles the authentication) and any other parameters needed for the implementation.

To configure a realm that uses a JDBC database connection to authenticate users, the realm implementation classname is org.apache.catalina.realm.JDBCRealm. The JDBC realm requires two database tables: one that associates users with roles and another that associates users with their credentials (passwords). Table A.1 shows the additional configuration attributes you must specify in the <Realm> element when using the JDBC realm.

Table A.1. Attributes of the Realm Element

Attribute	Description
className	The classname for the JDBC realm implementation; must be org.apache.catalina.realm.JDBCRealm.
connectionName	The database username used by the JDBC connection.
connectionPassword	The database password used by the JDBC connection.
connectionURL	The JDBC URL used by the JDBC connection.
driverName	The classname of the JDBC driver used for this database.
roleNameCol	The name of the column in the userRoleTable table that contains the user's role.
userCredCol	The name of the column in the userTable table that contains the user's password.
userNameCol	The name of the column in both the userTable and userRoleTable tables that contains the username.
userRoleTable	The name of the table containing roles and usernames. There should be one row for each unique combination of username and role. The roleNameCol and userNameCol attributes define the names of the columns in this table that contain the roles and usernames.
userTable	The name of the table containing usernames and passwords. There should be one row for each unique username and password. The userNameCol and userCredCol attributes specify the names of the columns that contain usernames and passwords.

In addition to these required attributes, there are two options attributes. The debug attribute indicates the amount of logging that the JDBC realm should perform. The default value is 0, which is the minimum amount of logging. Higher numbers indicate more logging. The digest attribute indicates that instead of using plaintext for passwords, you should use a message digest algorithm for storing and comparing passwords. The value of this attribute must be one of Java's supported message digest algorithms (MD5, SHA1).

Listing A.1 shows an example JDBC realm declaration.

Listing A.1 JDBC Realm Declaration for Tomcat

<Realm className="org.apache.catalina.realm.JDBCRealm"
    driverName="org.gjt.mm.mysql.Driver"
    connectionName="mark"
    connectionPassword="markpass"
    connectionURL="jdbc:mysql://localhost/tomcat?user=mark&password=markpass"
    userTable="users"
    userRoleTable="roles"
    userNameCol="user"
    roleNameCol="role"
    userCredCol="password" />

Tomcat's other realm implementations support LDAP (through JNDI) and plaintext files. The plaintext file implementation is called the "Memory Realm" and isn't meant for production installations. However, it is the default realm. The LDAP support is fairly complicated to set up. You can find documentation for setting up an LDAP realm at http://jakarta.apache.org/tomcat.