386 lines
27 KiB
HTML
386 lines
27 KiB
HTML
|
<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Realm Component</title><meta name="author" value="Craig R. McClanahan"><meta name="email" value="craigmcc@apache.org"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
|
||
|
|
The Apache Tomcat Servlet/JSP Container
|
||
|
|
" border="0"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="true"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>Apache Tomcat Configuration Reference</h1><h2>The Realm Component</h2></td><td align="right" valign="top" nowrap="true"><small><a href="printer/realm.html"><img src="../images/printer.gif" border="0" alt="Printer Friendly Version"><br>print-friendly<br>version
|
||
|
|
</a></small></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>A <strong>Realm</strong> element represents a "database" of usernames,
|
||
|
|
passwords, and <em>roles</em> (similar to Unix <em>groups</em>) 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
|
||
|
|
<em>Container Managed Security</em> as described in the Servlet
|
||
|
|
Specification.</p>
|
||
|
|
|
||
|
|
<p>You may nest a Realm inside any Catalina container
|
||
|
|
<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
|
||
|
|
<a href="context.html">Context</a>). In addition, Realms associated with
|
||
|
|
an Engine or a Host are automatically inherited by lower-level
|
||
|
|
containers, unless explicitly overridden.</p>
|
||
|
|
|
||
|
|
<p>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
|
||
|
|
<a href="../realm-howto.html">Container-Managed Security Guide</a>.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<blockquote><em>
|
||
|
|
<p>The description below uses the variable name $CATALINA_HOME
|
||
|
|
to refer to the directory into which you have installed Tomcat 6,
|
||
|
|
and is the base directory against which most relative paths are
|
||
|
|
resolved. However, if you have configured Tomcat 6 for multiple
|
||
|
|
instances by setting a CATALINA_BASE directory, you should use
|
||
|
|
$CATALINA_BASE instead of $CATALINA_HOME for each of these
|
||
|
|
references.</p>
|
||
|
|
</em></blockquote>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>All implementations of <strong>Realm</strong>
|
||
|
|
support the following attributes:</p>
|
||
|
|
|
||
|
|
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>className</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Java class name of the implementation to use. This class must
|
||
|
|
implement the <code>org.apache.catalina.Realm</code> interface.</p>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standard Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>Unlike most Catalina components, there are several standard
|
||
|
|
<strong>Realm</strong> implementations available. As a result,
|
||
|
|
the <code>className</code> attribute MUST be used to select the
|
||
|
|
implementation you wish to use.</p>
|
||
|
|
|
||
|
|
<h3>JDBC Database Realm (org.apache.catalina.realm.JDBCRealm)</h3>
|
||
|
|
|
||
|
|
<p>The <strong>JDBC Database Realm</strong> 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.</p>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>connectionName</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The database username to use when establishing the JDBC
|
||
|
|
connection.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>connectionPassword</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The database password to use when establishing the JDBC
|
||
|
|
connection.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>connectionURL</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The connection URL to be passed to the JDBC driver when
|
||
|
|
establishing a database connection.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>digest</code></td><td align="left" valign="center">
|
||
|
|
<p>The name of the <code>MessageDigest</code> algorithm used
|
||
|
|
to encode user passwords stored in the database. If not specified,
|
||
|
|
user passwords are assumed to be stored in clear-text.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>digestEncoding</code></td><td align="left" valign="center">
|
||
|
|
<p>The charset for encoding digests. If not specified, the platform
|
||
|
|
default will be used.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>driverName</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Fully qualified Java class name of the JDBC driver to be
|
||
|
|
used to connect to the authentication database.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>roleNameCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Name of the column, in the "user roles" table, which contains
|
||
|
|
a role name assigned to the corresponding user.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userCredCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Name of the column, in the "users" table, which contains
|
||
|
|
the user's credentials (i.e. password(. If a value for the
|
||
|
|
<code>digest</code> 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.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userNameCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Name of the column, in the "users" and "user roles" table,
|
||
|
|
that contains the user's username.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userRoleTable</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Name of the "user roles" table, which must contain columns
|
||
|
|
named by the <code>userNameCol</code> and <code>roleNameCol</code>
|
||
|
|
attributes.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userTable</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Name of the "users" table, which must contain columns named
|
||
|
|
by the <code>userNameCol</code> and <code>userCredCol</code>
|
||
|
|
attributes.</p>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
|
||
|
|
information on setting up container managed security using the
|
||
|
|
JDBC Database Realm component.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>
|
||
|
|
DataSource Database Realm (org.apache.catalina.realm.DataSourceRealm)
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p>The <strong>DataSource Database Realm</strong> 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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>The DataSource Database Realm supports simultaneous realm based
|
||
|
|
authentications and allows the underlying JDBC DataSource to
|
||
|
|
handle optimizations like database connection pooling.</p>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>dataSourceName</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the JNDI JDBC DataSource for this Realm.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>digest</code></td><td align="left" valign="center">
|
||
|
|
<p>The name of the <code>MessageDigest</code> algorithm used
|
||
|
|
to encode user passwords stored in the database. If not specified,
|
||
|
|
user passwords are assumed to be stored in clear-text.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>roleNameCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Name of the column, in the "user roles" table, which contains
|
||
|
|
a role name assigned to the corresponding user.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userCredCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Name of the column, in the "users" table, which contains
|
||
|
|
the user's credentials (i.e. password(. If a value for the
|
||
|
|
<code>digest</code> 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.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userNameCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Name of the column, in the "users" and "user roles" table,
|
||
|
|
that contains the user's username.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userRoleTable</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Name of the "user roles" table, which must contain columns
|
||
|
|
named by the <code>userNameCol</code> and <code>roleNameCol</code>
|
||
|
|
attributes.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userTable</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Name of the "users" table, which must contain columns named
|
||
|
|
by the <code>userNameCol</code> and <code>userCredCol</code>
|
||
|
|
attributes.</p>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<p>See the <a href="../realm-howto.html#DataSourceRealm">
|
||
|
|
DataSource Realm HOW-TO</a> for more information on setting up container
|
||
|
|
managed security using the DataSource Database Realm component.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>JNDI Directory Realm (org.apache.catalina.realm.JNDIRealm)</h3>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The <strong>JNDI Directory Realm</strong> 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.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The directory realm supports a variety of approaches to using
|
||
|
|
LDAP for authentication:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>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.
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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.
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p> 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:</p>
|
||
|
|
|
||
|
|
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>alternateURL</code></td><td align="left" valign="center">
|
||
|
|
<p>If a socket connection can not be made to the provider at
|
||
|
|
the <code>connectionURL</code> an attempt will be made to use the
|
||
|
|
<code>alternateURL</code>.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>authentication</code></td><td align="left" valign="center">
|
||
|
|
<p>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.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>connectionName</code></td><td align="left" valign="center">
|
||
|
|
<p>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 <code>userPassword</code>
|
||
|
|
property.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>connectionPassword</code></td><td align="left" valign="center">
|
||
|
|
<p>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 <code>userPassword</code>
|
||
|
|
property.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>connectionURL</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The connection URL to be passed to the JNDI driver when
|
||
|
|
establishing a connection to the directory.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>contextFactory</code></td><td align="left" valign="center">
|
||
|
|
<p>Fully qualified Java class name of the factory class used
|
||
|
|
to acquire our JNDI <code>InitialContext</code>. By default,
|
||
|
|
assumes that the standard JNDI LDAP provider will be utilized.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>derefAliases</code></td><td align="left" valign="center">
|
||
|
|
<p>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.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>protocol</code></td><td align="left" valign="center">
|
||
|
|
<p>A string specifying the security protocol to use. If not given
|
||
|
|
the providers default is used.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>roleBase</code></td><td align="left" valign="center">
|
||
|
|
<p>The base directory entry for performing role searches. If
|
||
|
|
not specified the top-level element in the directory context
|
||
|
|
will be used.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>roleName</code></td><td align="left" valign="center">
|
||
|
|
<p>The name of the attribute that contains role names in the
|
||
|
|
directory entries found by a role search. In addition you can
|
||
|
|
use the <code>userRoleName</code> property to specify the name
|
||
|
|
of an attribute, in the user's entry, containing additional
|
||
|
|
role names. If <code>roleName</code> is not specified a role
|
||
|
|
search does not take place, and roles are taken only from the
|
||
|
|
user's entry.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>roleSearch</code></td><td align="left" valign="center">
|
||
|
|
<p>The LDAP filter expression used for performing role
|
||
|
|
searches. Use <code>{0}</code> to substitute the
|
||
|
|
distinguished name (DN) of the user, and/or <code>{1}</code> 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 <code>userRoleName</code>
|
||
|
|
property.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>roleSubtree</code></td><td align="left" valign="center">
|
||
|
|
<p>Set to <code>true</code> if you want to search the entire
|
||
|
|
subtree of the element specified by the <code>roleBase</code>
|
||
|
|
property for role entries associated with the user. The
|
||
|
|
default value of <code>false</code> causes only the top level
|
||
|
|
to be searched.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>userBase</code></td><td align="left" valign="center">
|
||
|
|
<p>The base element for user searches performed using the
|
||
|
|
<code>userSearch</code> expression. Not used if you are using
|
||
|
|
the <code>userPattern</code> expression.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>userPassword</code></td><td align="left" valign="center">
|
||
|
|
<p>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
|
||
|
|
<code>connectionName</code> and
|
||
|
|
<code>connectionPassword</code> properties, and retrieve the
|
||
|
|
corresponding attribute for comparison to the value specified
|
||
|
|
by the user being authenticated. If you do
|
||
|
|
<strong>not</strong> 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.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>userPattern</code></td><td align="left" valign="center">
|
||
|
|
<p>Pattern for the distinguished name (DN) of the user's
|
||
|
|
directory entry, with <code>{0}</code> marking where the
|
||
|
|
actual username should be inserted. You can use this property
|
||
|
|
instead of <code>userSearch</code>, <code>userSubtree</code>
|
||
|
|
and <code>userBase</code> when the distinguished name contains
|
||
|
|
the username and is otherwise the same for all users.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>userRoleName</code></td><td align="left" valign="center">
|
||
|
|
<p>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
|
||
|
|
<code>roleName</code> property to specify the name of an
|
||
|
|
attribute to be retrieved from individual role entries found
|
||
|
|
by searching the directory. If <code>userRoleName</code> is
|
||
|
|
not specified all the roles for a user derive from the role
|
||
|
|
search.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>userSearch</code></td><td align="left" valign="center">
|
||
|
|
<p>The LDAP filter expression to use when searching for a
|
||
|
|
user's directory entry, with <code>{0}</code> marking where
|
||
|
|
the actual username should be inserted. Use this property
|
||
|
|
(along with the <code>userBase</code> and
|
||
|
|
<code>userSubtree</code> properties) instead of
|
||
|
|
<code>userPattern</code> to search the directory for the
|
||
|
|
user's entry.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>userSubtree</code></td><td align="left" valign="center">
|
||
|
|
<p>Set to <code>true</code> if you want to search the entire
|
||
|
|
subtree of the element specified by the <code>userBase</code>
|
||
|
|
property for the user's entry. The default value of
|
||
|
|
<code>false</code> causes only the top level to be searched.
|
||
|
|
Not used if you are using the <code>userPattern</code>
|
||
|
|
expression.</p>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
|
||
|
|
information on setting up container managed security using the
|
||
|
|
JNDI Directory Realm component.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Memory Based Realm (org.apache.catalina.realm.MemoryRealm)</h3>
|
||
|
|
|
||
|
|
<p>The <strong>Memory Based Realm</strong> 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.</p>
|
||
|
|
|
||
|
|
<p>The Memory Based Realm implementation supports the following
|
||
|
|
additional attributes:</p>
|
||
|
|
|
||
|
|
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>pathname</code></td><td align="left" valign="center">
|
||
|
|
<p>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 <code>conf/tomcat-users.xml</code>.</p>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<p>The XML document referenced by the <code>pathname</code> attribute must
|
||
|
|
conform to the following requirements:</p>
|
||
|
|
<ul>
|
||
|
|
<li>The root (outer) element must be <code><tomcat-users></code>.
|
||
|
|
</li>
|
||
|
|
<li>Each authorized user must be represented by a single XML element
|
||
|
|
<code><user></code>, nested inside the root element.</li>
|
||
|
|
<li>Each <code><user></code> element must have the following
|
||
|
|
attributes:
|
||
|
|
<ul>
|
||
|
|
<li><strong>name</strong> - Username of this user (must be unique
|
||
|
|
within this file).</li>
|
||
|
|
<li><strong>password</strong> - Password of this user (in
|
||
|
|
clear text).</li>
|
||
|
|
<li><strong>roles</strong> - Comma-delimited list of the role names
|
||
|
|
assigned to this user.</li>
|
||
|
|
</ul></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
|
||
|
|
information on setting up container managed security using the
|
||
|
|
Memory Based Realm component.</p>
|
||
|
|
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>No components may be nested inside a <strong>Realm</strong> element.</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Special Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>See <a href="host.html">Single Sign On</a> for information about
|
||
|
|
configuring Single Sign On support for a virtual host.</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
|
||
|
|
Copyright © 1999-2006, Apache Software Foundation
|
||
|
|
</em></font></div></td></tr></table></body></html>
|