Realm Configuration HOW-TO
Table of Contents
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 here.
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 JDBC DataSource.
- 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) framework.
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 .../&g