Apache Tomcat Development
Realm Configuration HOW-TO
This document describes how to configure Tomcat to support container
managed security, by connecting to an existing "database" of usernames,
passwords, and user roles. You only need to care about this if you are using
a web application that includes one or more
<security-constraint> elements, and a
<login-config> element defining how users are required
to authenticate themselves. If you are not utilizing these features, you can
safely skip this document.
For fundamental background information about container managed security,
see the Servlet
Specification (Version 2.4), Section 12.
For information about utilizing the Single Sign On feature of
Tomcat (allowing a user to authenticate themselves once across the entire
set of web applications associated with a virtual host), see
|What is a Realm?|
A Realm is a "database" of usernames and passwords that
identify valid users of a web application (or set of web applications), plus
an enumeration of the list of roles associated with each valid user.
You can think of roles as similar to groups in Unix-like operating
systems, because access to specific web application resources is granted to
all users possessing a particular role (rather than enumerating the list of
associated usernames). A particular user can have any number of roles
associated with their username.
Although the Servlet Specification describes a portable mechanism for
applications to declare their security requirements (in the
web.xml deployment descriptor), there is no portable API
defining the interface between a servlet container and the associated user
and role information. In many cases, however, it is desirable to "connect"
a servlet container to some existing authentication database or mechanism
that already exists in the production environment. Therefore, Tomcat
defines a Java interface (
can be implemented by "plug in" components to establish this connection.
Six standard plug-ins are provided, supporting connections to various
sources of authentication information:
- JDBCRealm - Accesses authentication information
stored in a relational database, accessed via a JDBC driver.
- DataSourceRealm - Accesses authentication
information stored in a relational database, accessed via a named JNDI
- JNDIRealm - Accesses authentication information
stored in an LDAP based directory server, accessed via a JNDI provider.
- UserDatabaseRealm - Accesses authentication
information stored in an UserDatabase JNDI resource, which is typically
backed by an XML document (
- MemoryRealm - Accesses authentication
information stored in an in-memory object collection, which is initialized
from an XML document (
- JAASRealm - Accesses authentication information
through the Java Authentication & Authorization Service (JAAS)
It is also possible to write your own
and integrate it with Tomcat. To do so, you need to:
- Place your compiled realm in $CATALINA_HOME/lib,
- Declare your realm as described in the "Configuring a Realm" section below,
- Declare your realm to the MBeans Descriptors.
|Configuring a Realm|
Before getting into the details of the standard Realm implementations, it is
important to understand, in general terms, how a Realm is configured. In
general, you will be adding an XML element to your
configuration file, that looks something like this:
<Realm className="... class name for this implementation"
... other attributes for this implementation .../>
<Realm> element can be nested inside any one of
of the following
Container elements. The location of the
Realm element has a direct impact on the "scope" of that Realm
(i.e. which web applications will share the same authentication information):
- Inside an <Engine> element - This Realm will be shared
across ALL web applications on ALL virtual hosts, UNLESS it is overridden
by a Realm element nested inside a subordinate
- Inside a <Host> element - This Realm will be shared across
ALL web applications for THIS virtual host, UNLESS it is overridden
by a Realm element nested inside a subordinate
- Inside a <Context> element - This Realm will be used ONLY
for THIS web application.
For each of the standard
Realm implementations, the
user's password (by default) is stored in clear text. In many
environments, this is undesirable because casual observers of the
authentication data can collect enough information to log on
successfully, and impersonate other users. To avoid this problem, the
standard implementations support the concept of digesting
user passwords. This allows the stored version of the passwords to be
encoded (in a form that is not easily reversible), but that the
Realm implementation can still utilize for
When a standard realm authenticates by retrieving the stored
password and comparing it with the value presented by the user, you
can select digested passwords by specifying the
attribute on your
<Realm> element. The value for
this attribute must be one of the digest algorithms supported by the
java.security.MessageDigest class (SHA, MD2, or MD5).
When you select this option, the contents of the password that is
stored in the
Realm must be the cleartext version of the
password, as digested by the specified algorithm.
authenticate() method of the Realm is called, the
(cleartext) password specified by the user is itself digested by the same
algorithm, and the result is compared with the value returned by the
Realm. An equal match implies that the cleartext version of the
original password is the same as the one presented by the user, so