Tomcat JDBCRealm

JDBCRealm

Introduction JDBCRealm is an implementation of the Tomcat Realm interface that looks up users in a relational database accessed via a JDBC driver. There is substantial configuration flexibility that lets you adapt to existing table and column names, as long as your database structure conforms to the following requirements: There must be a table, referenced below as the users table, that contains one row for every valid user that this Realm should recognize. The users table must contain at least two columns (it may contain more if your existing applications required it): Username to be recognized by Tomcat when the user logs in. Password to be recognized by Tomcat when the user logs in. This value may in cleartext or digested - see below for more information. There must be a table, referenced below as the user roles table, that contains one row for every valid role that is assigned to a particular user. It is legal for a user to have zero, one, or more than one valid role. The user roles table must contain at least two columns (it may contain more if your existing applications required it): Username to be recognized by Tomcat (same value as is specified in the users table). Role name of a valid role associated with this user. Quick Start To set up Tomcat to use JDBCRealm, you will need to follow these steps: If you have not yet done so, create tables and columns in your database that conform to the requirements described above. Configure a database username and password for use by Tomcat, that has at least read only access to the tables described above. (Tomcat will never attempt to write to these tables.) Place a copy of the JDBC driver you will be using inside the $CATALINA_HOME/lib directory. Note that only JAR files are recognized! Set up a <Realm> element, as described below, in your $CATALINA_BASE/conf/server.xml file. Restart Tomcat if it is already running. Realm Element Attributes To configure JDBCRealm, you will create a <Realm> element and nest it in your$CATALINA_BASE/conf/server.xml file, as described above. The attributes for the JDBCRealm are defined in the Realm configuration documentation. Example An example SQL script to create the needed tables might look something like this (adapt the syntax as required for your particular database): create table users ( user_name varchar(15) not null primary key, user_pass varchar(15) not null ); create table user_roles ( user_name varchar(15) not null, role_name varchar(15) not null, primary key (user_name, role_name) ); Example Realm elements are included (commented out) in the default $CATALINA_BASE/conf/server.xmlfile. Here's an example for using a MySQL database called "authority", configured with the tables described above, and accessed with username "dbuser" and password "dbpass": <Realm className="org.apache.catalina.realm.JDBCRealm" driverName="com.mysql.jdbc.Driver" connectionURL="jdbc:mysql://localhost/authority?user=dbuser&amp;password=dbpass" userTable="users" userNameCol="user_name" userCredCol="user_pass" userRoleTable="user_roles" roleNameCol="role_name"/> Additional Notes JDBCRealm operates according to the following rules: When a user attempts to access a protected resource for the first time, Tomcat will call theauthenticate() method of this Realm. Thus, any changes you have made to the database directly (new users, changed passwords or roles, etc.) will be immediately reflected. Once a user has been authenticated, the user (and his or her associated roles) are cached within Tomcat for the duration of the user's login. (For FORM-based authentication, that means until the session times out or is invalidated; for BASIC authentication, that means until the user closes their browser). The cached user is not saved and restored across sessions serialisations. Any changes to the database information for an already authenticated user will not be reflected until the next time that user logs on again. Administering the information in the users and user roles table is the responsibility of your own applications. Tomcat does not provide any built-in capabilities to maintain users and roles.