The Realm Component

Overview

A Realm element represents a "database" of usernames, passwords, and roles (similar to Unix groups) assigned to those users. Different implementations of Realm allow Catalina to be integrated into environments where such authentication information is already being created and maintained, and then utilize that information to implement Container Managed Security as described in the Servlet Specification.

You may nest a Realm inside any Catalina container Engine, Host, or Context. In addition, Realms associated with an Engine or a Host are automatically inherited by lower-level containers, unless explicitly overridden.

For more in-depth information about container managed security in web applications, see FIXME - link to "Container Managed Security Guide" in the application developer's section. For more in-depth information about configuing and using the standard Realm component implementations, see FIXME - link to "Realm Configuration HOW-TO" in the administrator's section.

Attributes

Attribute Description

className Java class name of the implementation to use. This class must implement the org.apache.catalina.Realm interface.

Standard Implementation

Unlike most Catalina components, there are several standard Realm implementations available. As a result, the className attribute MUST be used to select the implementation you wish to use.

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 that it is required, changes to the database will be immediately reflected in the information used to authenticate new logins.

A rich set of additional attributes lets you configure the required connection to the underlying database, as well as the table and column names used to retrieve the required information:

Attribute Description

connectionName The database username to use when establishing the JDBC connection.

connectionPassword The database password to use when establishing the JDBC connection.

connectionURL The connection URL to be passed to the JDBC driver when establishing a database connection.

digest The name of the MessageDigest algorithm used to encode user passwords stored in the database. If not specified, user passwords are assumed to be stored in clear-text.

driverName Fully qualified Java class name of the JDBC driver to be used to connect to the authentication database.

roleNameCol Name of the column, in the "user roles" table, which contains a role name assigned to the corresponding user.

userCredCol Name of the column, in the "users" table, which contains the user's credentials (i.e. password(. If a value for the digest attribute is specified, this component will assume that the passwords have been encoded with the specified algorithm. Otherwise, they will be assumed to be in clear text.

userNameCol Name of the column, in the "users" and "user roles" table, that contains the user's username.

userRoleTable Name of the "user roles" table, which must contain columns named by the userNameCol and roleNameCol attributes.

userTable Name of the "users" table, which must contain columns named by the userNameCol and userCredCol attributes.

See FIXME - Nested pointer into HOW-TO for more information on setting up container managed security using the JDBC Database Realm component.

JNDI Directory Realm (org.apache.catalina.realm.JNDIRealm)

The JNDI Directory Realm connects Catalina to an LDAP Directory, accessed through an appropriate JNDI driver, to perform lookups of usernames, passwords, and their associated roles. Because the lookup is done each time that it is required, changes to the directory will be immediately reflected in the information used to authenticate new logins.

A rich set of additional attributes lets you configure the required connection to the underlying directory, as well as the element and attribute names used to retrieve the required information:

Attribute Description

connectionName The directory username to use when establishing the JNDI connection.

connectionPassword The directory password to use when establishing the JNDI connection.

connectionURL The connection URL to be passed to the JNDI driver when establishing a connection to the directory.

contextFactory Fully qualified Java class name of the factory class used to acquire our JNDI InitialContext. By default, assumes that the standard JNDI LDAP provider will be utilized.

roleBase The base directory element for performing role searches.

roleName The name of the directory attribute to retrieve when selecting the assigned roles for a user.

roleSearch The LDAP search expression to use when selecting roles for a particular user, with {0} marking where the actual username should be inserted.

roleSubtree Set to true to search subtrees of the elements selected by the roleSearch search expression. Set to false to not search subtrees.

userPassword Name of the LDAP element containing the user's password.

userPattern The LDAP search expression to use when retrieving the attributes of a particular user, with {0} marking where the actual username should be inserted.

See FIXME - Nested pointer into HOW-TO for more information on setting up container managed security using the JNDI Directory Realm component.

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

The Memory Based Realm is a simple Realm implementation that reads user information from an XML format, and represents it as a collection of Java objects in memory. This implementation is intended solely to get up and running with container managed security - it is NOT intended for production use. As such, there are no mechanisms for updating the in-memory collection of users when the content of the underlying data file is changed.

The Memory Based Realm implementation supports the following additional attributes:

Attribute Description

pathname Absolute or relative (to $CATALINA_HOME) pathname to the XML file containing our user information. See below for details on the XML element format required. If no pathname is specified, the default value is conf/tomcat-users.xml.

The XML document referenced by the pathname attribute must conform to the following requirements:

The root (outer) element must be <tomcat-users>.

Each authorized user must be represented by a single XML element <user>, nested inside the root element.

Each <user> element must have the following attributes:

name - Username of this user (must be unique within this file).

password - Password of this user (in clear text).

roles - Comma-delimited list of the role names assigned to this user.

See FIXME - Nested pointer into HOW-TO for more information on setting up container managed security using the Memory Based Realm component.

Special Features

See Single Sign On for information about configuring Single Sign On support for a virtual host.

Attribute	Description
connectionName	The database username to use when establishing the JDBC connection.
connectionPassword	The database password to use when establishing the JDBC connection.
connectionURL	The connection URL to be passed to the JDBC driver when establishing a database connection.
digest	The name of the MessageDigest algorithm used to encode user passwords stored in the database. If not specified, user passwords are assumed to be stored in clear-text.
driverName	Fully qualified Java class name of the JDBC driver to be used to connect to the authentication database.
roleNameCol	Name of the column, in the "user roles" table, which contains a role name assigned to the corresponding user.
userCredCol	Name of the column, in the "users" table, which contains the user's credentials (i.e. password(. If a value for the digest attribute is specified, this component will assume that the passwords have been encoded with the specified algorithm. Otherwise, they will be assumed to be in clear text.
userNameCol	Name of the column, in the "users" and "user roles" table, that contains the user's username.
userRoleTable	Name of the "user roles" table, which must contain columns named by the userNameCol and roleNameCol attributes.
userTable	Name of the "users" table, which must contain columns named by the userNameCol and userCredCol attributes.

Attribute	Description
connectionName	The directory username to use when establishing the JNDI connection.
connectionPassword	The directory password to use when establishing the JNDI connection.
connectionURL	The connection URL to be passed to the JNDI driver when establishing a connection to the directory.
contextFactory	Fully qualified Java class name of the factory class used to acquire our JNDI InitialContext. By default, assumes that the standard JNDI LDAP provider will be utilized.
roleBase	The base directory element for performing role searches.
roleName	The name of the directory attribute to retrieve when selecting the assigned roles for a user.
roleSearch	The LDAP search expression to use when selecting roles for a particular user, with {0} marking where the actual username should be inserted.
roleSubtree	Set to true to search subtrees of the elements selected by the roleSearch search expression. Set to false to not search subtrees.
userPassword	Name of the LDAP element containing the user's password.
userPattern	The LDAP search expression to use when retrieving the attributes of a particular user, with {0} marking where the actual username should be inserted.