Links User Guide Reference Apache Tomcat Development | Realm Configuration HOW-TO| Quick Start |
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.
|
| Overview |
| 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 (org.apache.catalina.Realm) that
can be implemented by "plug in" components to establish this connection.
Five 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 (
conf/tomcat-users.xml).
- MemoryRealm - Accesses authentication
information stored in an in-memory object collection, which is initialized
from an XML document (
conf/tomcat-users.xml).
- JAASRealm - Accesses authentication information
through the Java Authentication & Authorization Service (JAAS)
framework.
It is also possible to write your own Realm implementation,
and integrate it with Tomcat. To do so, you need to:
- Implement
org.apache.catalina.Realm,
- 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 Descriptor.
|
|
| Common Features |
| Digested Passwords |
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
authentication.
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 digest
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.
When the 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 that this
user should be authorized.
To calculate the digested value of a cleartext password, two convenience
techniques are supported:
- If you are writing an application that needs to calculate digested
passwords dynamically, call the static
Digest() method of the
org.apache.catalina.realm.RealmBase class, passing the
cleartext password and the digest algorithm name as arguments. This
method will return the digested password.
- If you want to execute a command line utility to calculate the digested
password, simply execute
|
|
|
