The Realm Component

Introduction

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, as well as more information on configuring and using the standard realm component implementations, please see the Container-Managed Security Guide.

The description below uses the variable name $CATALINA_HOME to refer to the directory into which you have installed JBoss Web, and is the base directory against which most relative paths are resolved. However, if you have configured JBoss Web for multiple instances by setting a CATALINA_BASE directory, you should use $CATALINA_BASE instead of $CATALINA_HOME for each of these references.

Attributes

Common Attributes

All implementations of Realm 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.

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.

digestEncoding
The charset for encoding digests. If not specified, the platform default will be used.

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 the Container-Managed Security Guide for more information on setting up container managed security using the JDBC Database Realm component.

Combined Realm (org.apache.catalina.realm.CombinedRealm)

CombinedRealm is an implementation of the Tomcat 6 Realm interface that authenticates users through one or more sub-Realms.

Using CombinedRealm gives the developer the ability to combine multiple Realms of the same or different types. This can be used to authenticate against different sources, provide fall back in case one Realm fails or for any other purpose that requires multiple Realms.

Sub-realms are defined by nesting Realm elements inside the Realm element that defines the CombinedRealm. Authentication will be attempted against each Realm in the order they are listed. Authentication against any Realm will be sufficient to authenticate the user.

The Combined Realm implementation does not support any additional attributes.

See the Container-Managed Security Guide for more information on setting up container managed security using the Combined Realm component.

DataSource Database Realm (org.apache.catalina.realm.DataSourceRealm)

The DataSource Database Realm connects Catalina to a relational database, accessed through a JNDI named JDBC DataSource 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.

The JDBC Realm uses a single db connection. This requires that realm based authentication be synchronized, i.e. only one authentication can be done at a time. This could be a bottleneck for applications with high volumes of realm based authentications.

The DataSource Database Realm supports simultaneous realm based authentications and allows the underlying JDBC DataSource to handle optimizations like database connection pooling.

A rich set of additional attributes lets you configure the name of the JNDI JDBC DataSource, as well as the table and column names used to retrieve the required information:

Attribute Description
dataSourceName
The name of the JNDI JDBC DataSource for this Realm.

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.

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 the DataSource Realm HOW-TO for more information on setting up container managed security using the DataSource 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, that stores usernames, passwords, and their associated roles. Changes to the directory are immediately reflected in the information used to authenticate new logins.

The directory realm supports a variety of approaches to using LDAP for authentication:

The realm can either use a pattern to determine the distinguished name (DN) of the user's directory entry, or search the directory to locate that entry.

The realm can authenticate the user either by binding to the directory with the DN of the user's entry and the password presented by the user, or by retrieving the password from the user's entry and performing a comparison locally.

Roles may be represented in the directory as explicit entries found by a directory search (e.g. group entries of which the user is a member), as the values of an attribute in the user's entry, or both.

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

Attribute Description
alternateURL
If a socket connection can not be made to the provider at the connectionURL an attempt will be made to use the alternateURL.

authentication
A string specifying the type of authentication to use. "none", "simple", "strong" or a provider specific definition can be used. If no value is given the providers default is used.

connectionName
The directory username to use when establishing a connection to the directory for LDAP search operations. If not specified an anonymous connection is made, which is often sufficient unless you specify the userPassword property.

connectionPassword
The directory password to use when establishing a connection to the directory for LDAP search operations. If not specified an anonymous connection is made, which is often sufficient unless you specify the userPassword property.

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.

derefAliases
A string specifying how aliases are to be dereferenced during search operations. The allowed values are "always", "never", "finding" and "searching". If not specified, "always" is used.

protocol
A string specifying the security protocol to use. If not given the providers default is used.

roleBase
The base directory entry for performing role searches. If not specified the top-level element in the directory context will be used.

roleName
The name of the attribute that contains role names in the directory entries found by a role search. In addition you can use the userRoleName property to specify the name of an attribute, in the user's entry, containing additional role names. If roleName is not specified a role search does not take place, and roles are taken only from the user's entry.

roleSearch
The LDAP filter expression used for performing role searches. Use {0} to substitute the distinguished name (DN) of the user, and/or {1} to substitute the username. If not specified a role search does not take place and roles are taken only from the attribute in the user's entry specified by the userRoleName property.

roleSubtree
Set to true if you want to search the entire subtree of the element specified by the roleBase property for role entries associated with the user. The default value of false causes only the top level to be searched.

userBase
The base element for user searches performed using the userSearch expression. Not used if you are using the userPattern expression.

userPassword
Name of the attribute in the user's entry containing the user's password. If you specify this value, JNDIRealm will bind to the directory using the values specified by connectionName and connectionPassword properties, and retrieve the corresponding attribute for comparison to the value specified by the user being authenticated. If you do not specify this value, JNDIRealm will attempt a simple bind to the directory using the DN of the user's entry and the password presented by the user, with a successful bind being interpreted as an authenticated user.

userPattern
Pattern for the distinguished name (DN) of the user's directory entry, with {0} marking where the actual username should be inserted. You can use this property instead of userSearch, userSubtree and userBase when the distinguished name contains the username and is otherwise the same for all users.

userRoleName
The name of an attribute in the user's directory entry containing zero or more values for the names of roles assigned to this user. In addition you can use the roleName property to specify the name of an attribute to be retrieved from individual role entries found by searching the directory. If userRoleName is not specified all the roles for a user derive from the role search.

userSearch
The LDAP filter expression to use when searching for a user's directory entry, with {0} marking where the actual username should be inserted. Use this property (along with the userBase and userSubtree properties) instead of userPattern to search the directory for the user's entry.

userSubtree
Set to true if you want to search the entire subtree of the element specified by the userBase property for the user's entry. The default value of false causes only the top level to be searched. Not used if you are using the userPattern expression.

See the Container-Managed Security Guide 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 the Container-Managed Security Guide for more information on setting up container managed security using the Memory Based Realm component.

Nested Components

Combined Realm Implementation

If you are using the Combined Realm Implementation <Realm> elements may be nested inside it.

Other Realm Implementations

No other Realm implementation supports nested components.

Special Features

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

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

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.
`digestEncoding`	The charset for encoding digests. If not specified, the platform default will be used.
`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
`dataSourceName`	The name of the JNDI JDBC DataSource for this Realm.
`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.
`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
`alternateURL`	If a socket connection can not be made to the provider at the `connectionURL` an attempt will be made to use the `alternateURL`.
`authentication`	A string specifying the type of authentication to use. "none", "simple", "strong" or a provider specific definition can be used. If no value is given the providers default is used.
`connectionName`	The directory username to use when establishing a connection to the directory for LDAP search operations. If not specified an anonymous connection is made, which is often sufficient unless you specify the `userPassword` property.
`connectionPassword`	The directory password to use when establishing a connection to the directory for LDAP search operations. If not specified an anonymous connection is made, which is often sufficient unless you specify the `userPassword` property.
`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.
`derefAliases`	A string specifying how aliases are to be dereferenced during search operations. The allowed values are "always", "never", "finding" and "searching". If not specified, "always" is used.
`protocol`	A string specifying the security protocol to use. If not given the providers default is used.
`roleBase`	The base directory entry for performing role searches. If not specified the top-level element in the directory context will be used.
`roleName`	The name of the attribute that contains role names in the directory entries found by a role search. In addition you can use the `userRoleName` property to specify the name of an attribute, in the user's entry, containing additional role names. If `roleName` is not specified a role search does not take place, and roles are taken only from the user's entry.
`roleSearch`	The LDAP filter expression used for performing role searches. Use `{0}` to substitute the distinguished name (DN) of the user, and/or `{1}` to substitute the username. If not specified a role search does not take place and roles are taken only from the attribute in the user's entry specified by the `userRoleName` property.
`roleSubtree`	Set to `true` if you want to search the entire subtree of the element specified by the `roleBase` property for role entries associated with the user. The default value of `false` causes only the top level to be searched.
`userBase`	The base element for user searches performed using the `userSearch` expression. Not used if you are using the `userPattern` expression.
`userPassword`	Name of the attribute in the user's entry containing the user's password. If you specify this value, JNDIRealm will bind to the directory using the values specified by `connectionName` and `connectionPassword` properties, and retrieve the corresponding attribute for comparison to the value specified by the user being authenticated. If you do not specify this value, JNDIRealm will attempt a simple bind to the directory using the DN of the user's entry and the password presented by the user, with a successful bind being interpreted as an authenticated user.
`userPattern`	Pattern for the distinguished name (DN) of the user's directory entry, with `{0}` marking where the actual username should be inserted. You can use this property instead of `userSearch`, `userSubtree` and `userBase` when the distinguished name contains the username and is otherwise the same for all users.
`userRoleName`	The name of an attribute in the user's directory entry containing zero or more values for the names of roles assigned to this user. In addition you can use the `roleName` property to specify the name of an attribute to be retrieved from individual role entries found by searching the directory. If `userRoleName` is not specified all the roles for a user derive from the role search.
`userSearch`	The LDAP filter expression to use when searching for a user's directory entry, with `{0}` marking where the actual username should be inserted. Use this property (along with the `userBase` and `userSubtree` properties) instead of `userPattern` to search the directory for the user's entry.
`userSubtree`	Set to `true` if you want to search the entire subtree of the element specified by the `userBase` property for the user's entry. The default value of `false` causes only the top level to be searched. Not used if you are using the `userPattern` expression.

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`.