Links Top Level Elements Connectors Containers Nested Components | The Realm ComponentIntroduction |
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, see FIXME - link to "Container Managed Security Guide"
in the application developer's section. For more in-depth
information about configuing and using the standard Realm component
implementations, see FIXME - link to "Realm Configuration HOW-TO"
in the administrator's section.
The description below uses the variable name $CATALINA_HOME
to refer to the directory into which you have installed Tomcat 4,
and is the base directory against which most relative paths are
resolved. However, if you have configured Tomcat 4 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.
|
|
Standard Implementation |
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 |
---|
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.
| 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.
| driverName |
Fully qualified Java class name of the JDBC driver to be
used to connect to the authentication database.
| 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 |
Name of the "user roles" table, which must contain columns
named by the userNameCol and roleNameCol
attributes.
| userTable |
Name of the "users" table, which must contain columns named
by the userNameCol and userCredCol
attributes.
|
See FIXME - Nested pointer into HOW-TO for more
information on setting up container managed security using the
JDBC 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,
to perform lookups of usernames, passwords, and their associated
roles. Because the lookup is done each time that it is required,
changes to the directory 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 directory, as well as the element and
attribute names used to retrieve the required information:
Attribute | Description |
---|
connectionName |
The directory username to use when establishing the JNDI
connection. This attribute is required if you specify the
userPassword property, and not used otherwise.
| connectionPassword |
The directory password to use when establishing the JNDI
connection. This attribute is required if you specify the
userPassword property, and not used otherwise.
| 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.
| roleBase |
The base directory element for performing role searches.
| roleName |
The name of the directory attribute to retrieve when selecting
the assigned roles for a user. If not specified, use the
userRoleName property to specify the name of an
attribute, in the user's entry, that contains zero or more role
names assigned to this user.
| roleSearch |
The LDAP search expression to use when selecting roles for a
particular user, with {0} marking where the actual
username should be inserted.
| roleSubtree |
Set to true to search subtrees of the elements
selected by the roleSearch search expression. Set
to false to not search subtrees.
| userBase |
The base element for user searches performed using the
userSearch expression. Not used if you are using
the userPattern expression.
| userPassword |
Name of the LDAP element 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 you do not
specify this value, JNDIRealm will attempt to bind to the
directory using the username and password specified by the user,
with a successful bind being interpreted as an authenticated user.
| userPattern |
The LDAP search expression to use when retrieving the attributes
of a particular user, with {0} marking where the
actual username should be inserted. Use this property instead of
userSearch if you want to select a particular single
entry based on the username.
| userRoleName |
The name of a directory attribute, in the user's entry, containing
zero or more values for the names of roles assigned to this user. If
not specified, use the roleName property to specify
the name of a particular attribute that is retrieved from individual
role entries associated with this user.
| userSearch |
The LDAP search expression to use when retrieving the attributes
of a particular user, with {0} marking where the
actual username should be inserted. Use this property instead of
userPattern if you want to search the entire directory
(under the optional additional control of the userBase
and userSubtree properties) instead of retrieving a
particular named entry.
| userSubtree |
Set to true if you are using the
userSearch pattern to search for authenticated users,
and you want to search subtrees of the element specified by the
userBase element. The default value of false
causes only the specified level to be searched. Not used if you are
using the userPattern expression.
|
See FIXME - Nested pointer into HOW-TO for more
information on setting up container managed security using the
JNDI Directory Realm component.
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 |
---|
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 FIXME - Nested pointer into HOW-TO for more
information on setting up container managed security using the
Memory Based Realm component.
|
|
|