Links Top Level Elements Connectors Containers Nested Components Other | Apache Tomcat Configuration ReferenceThe 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 Tomcat 5,
and is the base directory against which most relative paths are
resolved. However, if you have configured Tomcat 5 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.
| digest |
The digest algorithm used to store passwords in non-plaintext
formats. Valid values are those accepted for the algorithm name by the
java.security.MessageDigest class. See
Digested Passwords
for more information. If not specified, passwords are stored in clear
text.
| digestEncoding |
The charset for encoding digests. If not specified, the platform
default will be used.
|
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 |
|---|
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.
| 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.
| driverName |
Fully qualified Java class name of the JDBC driver to be used to
connect to the authentication database. Consult the documentation for
your JDBC driver for the appropriate value.
| 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 |
The name of the table that contains one row for each role
assigned to a particular username. This table must include at
least the columns named by the userNameCol and
roleNameCol attributes.
| userTable |
The name of the table that contains one row for each
username to be recognized by Tomcat. This table must include
at least the 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.
|
| 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 |
|---|
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.
| dataSourceName |
The JNDI named JDBC DataSource for your database. If the DataSource
is local to the context, the name is relative to
java:/comp/env, and otherwise the name should match the
name used to define the global DataSource.
| 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, 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 |
The name of the table that contains one row for each role
assigned to a particular username. This table must include at
least the columns named by the userNameCol and
roleNameCol attributes.
| userTable |
The name of the table that contains one row for each
username to be recognized by Tomcat. This table must include
at least the 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 |
|---|
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.
| 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
(com.sun.jndi.ldap.LdapCtxFactory).
| 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,
following the syntax supported by the
java.text.MessageFormat class. 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. If not specified, the top level
element in the directory context will be used. 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 the digest attribute is set,
the specified digest algorithm is applied to the password offered by the
user before comparing it with the value retrieved from the directory. 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, following the syntax supported by the
java.text.MessageFormat class. 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.
|
| UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm |
The UserDatabase Realm is a Realm implementation
that is based on a UserDatabase resource made available through the global
JNDI resources configured for this Tomcat instance.
The UserDatabase Realm implementation supports the following
additional attributes:
| Attribute | Description |
|---|
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.
| resourceName |
The name of the global UserDatabase resource
that this realm will use for user, password and role information.
|
See the
Container-Managed Security Guide for more
information on setting up container managed security using the UserDatabase
Realm component and the
JNDI resources how-to for more
information on how to configure a UserDatabase resource.
|
| 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 |
|---|
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.
| 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.
|
| JAAS Realm - org.apache.catalina.realm.JAASRealm |
The JAAS Realm implementation supports the following additional
attributes:
| Attribute | Description |
|---|
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.
| appName |
The name of the application as configured in your login configuration
file (
JAAS LoginConfig).
| userClassNames |
A comma-seperated list of the names of the classes that you have made
for your user Principals.
| roleClassNames |
A comma-seperated list of the names of the classes that you have made
for your role Principals.
| useContextClassLoader |
Instructs JAASRealm to use the context class loader for loading the
user-specified LoginModule class and associated
Principal classes. The default value is true,
which is backwards-compatible with the way Tomcat 4 works. To load
classes using the container's classloader, specify false.
|
See the Container-Managed Security
Guide for more information on setting up container managed security
using the JASS Realm component.
|
|
|
