The Realm Component

[Introduction] [Common Attributes] [Standard Implementation Attributes] [Special Features]

Introduction

A Realm component represents a mechanism by which a "database" of usernames, passwords, and their associated security roles can be linked into Catalina, for the purpose of authenticating users and validating security constraints. A variety of standard implementations is available, or you can implement your own to customize Tomcat's behavior to utilize your own security infrastructure.

If you attach a Realm to an outer Container (such as an Engine, that Realm will be used for all nested Containers (Host and Context components), unless you specifically nest a different Realm inside the nested Container. If you are using the Single Sign On capability (see Special Features), you must share a Realm at either the Engine or Host level.

Common Attributes

All implementations of the Realm component support the following attributes:

Attribute	Description
`className`	Java class name of the implementation to use. This class must implement the `org.apache.catalina.Realm` interface. Because there is no single standard implementation, this attribute is required. See Standard Implementation Attributes for the names of the supported classes.

Standard Implementation Attributes

Unlike most other Catalina components, there is not a single standard implementation of the Realm component available. Instead, a variety of standard implementations are available for your use. To select one, use the specified value for the className attribute, and configure the remaining attributes as described below.

JDBC Database Realm (`org.apache.catalina.realm.JDBCRealm`)

The JDBC Database Realm connects Catalina to a relational database, accessed through an appropriate JDBC driver, to perform lookups of usernames, passwords, and their associated roles. Because the lookup is done each time it is required, changes to the database will be immediately reflected in the information used to authenticate new logins. A rich set of configuration attributes lets you customize the database to which Catalina will connect, as well as the names of relevant tables and columns within the database that contains the information of interest.

The JDBC Database Realm supports the following additional attributes:

Attribute	Description
connectionName	The database username to use when establishing the JDBC connection. This attribute is required.
connectionPassword	The database password to use when establishing the JDBC connection. This attribute is required.
connectionURL	The connection URL to be passed to the JDBC driver. This attribute is required.
digest	The name of the MessageDigest algorithm to be used to encode passwords in the database, or a zero-length string for no encoding. If not specified, no encoding is the default.
driverName	The fully qualified Java class name of the JDBC driver to be used. This attribute is required. (Note that the corresponding driver's JAR file needs to be placed in the $CATALINA_HOME/server directory in order to be accessible.
roleNameCol	The name of the column, in the "user roles" table, which contains the role name to be compared to. This attribute is required.
userCredCol	The name of the column, in the "users" table, which contains the user's credentials (i.e. password). This attribute is required.
userNameCol	The name of the column, in the "users" and "user roles" tables, which contains the username of the user being looked up. This attribute is required.
userRoleTable	The name of the table, in the associated database, containing the "user roles" information. This attribute is required.
userTable	The name of the table, in the associated database, containing the "users" information. This attribute is required.

In order to be used by the JDBC Database Realm, your database must conform to the following rules:

It must be possible for Catalina to establish a JDBC connection to this database, using the configuration parameters described above.
The database must contain a table containing "users" information, which must conform to the following rules:
- There must be exactly one row for each valid user.
- There must be a column, named by the userNameCol attribute, that contains the username of the user represented by this row.
- There must be a column, named by the userCredCol attribute, that contains the credentials (password) of the user represented by this row.
- The credentials must be encoded by the MessageDigest algorithm configured by the digest attribute.
- There must be at most one row for any specific username value.
The database must contain a table containing "user roles" information, which must conform to the following rules:
- There must be exactly one row for each valid role that is assigned to a particular valid user.
- There may be more than one row for each valid user, one for each role assigned to that user.
- A valid user may have zero rows in this table, if that user is not assigned to any roles.
- There must be a column, named by the userNameCol attribute, that contains the username of the user whose role assignment is represented by this row.
- There must be a column, named by the userRoleCol attribute, that contains the role name assigned to this user.

Once a user is successfully authenticated, the following methods of the HttpServletRequest interface will return useful values:

getRemoteUser() - Will return the username of the user who was authenticated.
getUserPrincipal() - Will return a synthesized java.security.Principal implementation object representing the user who was authenticated.
isUserInRole(String) - Will return true if the currently authenticated user has a valid assignment to the specified role.

Memory Based Realm (`org.apache.catalina.realm.MemoryRealm`)

The Memory Based Realm initializes a simple memory-based database from an XML configuration file (by default, $CATALINA_HOME/conf/tomcat-users.xml) when Tomcat is first initialized. The format of this file is consistent with the format of the corresponding file used in Tomcat 3.x versions. An instance of a Memory Based Realm is used in the example application that is shipped with Catalina.

The Memory Based Realm supports the following additional attributes:

Attribute	Description
`pathname`	Relative or absolute pathname of the configuration file used to initialize the contents of this Realm. If a relative path is specified, it is interpreted as relative to $CATALINA_HOME. If no pathname is specified the default value is "conf/tomcat-users.xml" (relative to the Catalina home directory).

The configuration file specified by the pathname attribute must be in XML format. It consists of an outer element named <tomcat-users>, along with one nested <user> element for each defined user. Each user element supports the following attributes:

name - The username of this user (must be unique among all users defined in this configuration file)
password - The corresponding login password, in clear text
roles - A comma-delimited list of the roles to which this user belongs, or a zero-length string for no role assignments

Once a user is successfully authenticated, the following methods of the HttpServletRequest interface will return useful values:

getRemoteUser() - Will return the username of the user who was authenticated.
getUserPrincipal() - Will return a synthesized java.security.Principal implementation object representing the user who was authenticated.
isUserInRole(String) - Will return true if the currently authenticated user has a valid assignment to the specified role.

Special Features

Single Sign On Support

Normally, an individual user will need to authenticate himself or herself to each web application individually, even if the underlying Realm is being shared across an entire virtual host. Often, it is desirable for the user to be required to authenticate only once, and have that identity recognized across all of the web applications for this host.

Tomcat includes Single Sign On support to enable this. The detailed configuration requirements can be found here.