The Apache Tomcat Servlet/JSP Container

Apache Tomcat 7

Version 7.0.108, Jan 28 2021		Apache Logo

Links

Top Level Elements

Executors

Connectors

Containers

Nested Components

Cluster Elements

web.xml

Other

The Realm Component

Table of Contents
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.

A Catalina container (Engine, Host, or Context) may contain no more than one Realm element (although if supported by the Realm this one Realm may itself contain multiple nested Realms). In addition, the Realm associated with an Engine or a Host is automatically inherited by lower-level containers unless the lower level container explicitly defines its own Realm. If no Realm is configured for the Engine, an instance of the Null Realm will be configured for the Engine automatically.

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_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have installed Tomcat.

Attributes
Common Attributes

All implementations of Realm support the following attributes:

AttributeDescription
className

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

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.

DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm

The DataSource Database Realm connects Tomcat 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:

AttributeDescription
allRolesMode

This attribute controls how the special role name * is handled when processing authorization constraints in web.xml. By default, the specification compliant value of strict is used which means that the user must be assigned one of the roles defined in web.xml. The alternative values are authOnly which means that the user must be authenticated but no check is made for assigned roles and strictAuthOnly which means that the user must be authenticated and no check will be made for assigned roles unless roles are defined in web.xml in which case the user must be assigned at least one of those roles.

When this attribute has the value of authOnly or strictAuthOnly, the roleNameCol and userRoleTable attributes become optional. If those two attributes are omitted, the user's roles will not be loaded by this Realm.

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.

localDataSource

When the realm is nested inside a Context element, this allows the realm to use a DataSource defined for the Context rather than a global DataSource. If not specified, the default is false: use a global DataSource.

roleNameCol

Name of the column, i