You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2006/10/30 00:45:18 UTC
svn commit: r469024 - in /tomcat/container/tc5.5.x/webapps/docs:
config/realm.xml realm-howto.xml
Author: markt
Date: Sun Oct 29 15:45:16 2006
New Revision: 469024
URL: http://svn.apache.org/viewvc?view=rev&rev=469024
Log:
Put the realm attributes in a single place. Duplicating the attributes meant the neither location was correct. Having a single location should prevent a similar divergence in future. Add the UserDatabaseRealm.
Modified:
tomcat/container/tc5.5.x/webapps/docs/config/realm.xml
tomcat/container/tc5.5.x/webapps/docs/realm-howto.xml
Modified: tomcat/container/tc5.5.x/webapps/docs/config/realm.xml
URL: http://svn.apache.org/viewvc/tomcat/container/tc5.5.x/webapps/docs/config/realm.xml?view=diff&rev=469024&r1=469023&r2=469024
==============================================================================
--- tomcat/container/tc5.5.x/webapps/docs/config/realm.xml (original)
+++ tomcat/container/tc5.5.x/webapps/docs/config/realm.xml Sun Oct 29 15:45:16 2006
@@ -63,6 +63,20 @@
implement the <code>org.apache.catalina.Realm</code> interface.</p>
</attribute>
+ <attribute name="digest" required="false">
+ <p>The digest algorithm used to store passwords in non-plaintext
+ formats. Valid values are those accepted for the algorithm name by the
+ <code>java.security.MessageDigest</code> class. See
+ <a href="../realm-howto.html#Digested Passwords">Digested Passwords</a>
+ for more information. If not specified, passwords are stored in clear
+ text.</p>
+ </attribute>
+
+ <attribute name="digestEncoding" required="false">
+ <p>The charset for encoding digests. If not specified, the platform
+ default will be used.</p>
+ </attribute>
+
</attributes>
</subsection>
@@ -105,20 +119,10 @@
establishing a database connection.</p>
</attribute>
- <attribute name="digest" required="false">
- <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>
- </attribute>
-
- <attribute name="digestEncoding" required="false">
- <p>The charset for encoding digests. If not specified, the platform
- default will be used.</p>
- </attribute>
-
<attribute name="driverName" required="true">
- <p>Fully qualified Java class name of the JDBC driver to be
- used to connect to the authentication database.</p>
+ <p>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.</p>
</attribute>
<attribute name="roleNameCol" required="true">
@@ -127,12 +131,11 @@
</attribute>
<attribute name="userCredCol" required="true">
- <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>
+ <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>
</attribute>
<attribute name="userNameCol" required="true">
@@ -141,15 +144,17 @@
</attribute>
<attribute name="userRoleTable" required="true">
- <p>Name of the "user roles" table, which must contain columns
- named by the <code>userNameCol</code> and <code>roleNameCol</code>
- attributes.</p>
+ <p>The name of the table that contains one row for each <em>role</em>
+ assigned to a particular <em>username</em>. This table must include at
+ least the columns named by the <code>userNameCol</code> and
+ <code>roleNameCol</code> attributes.</p>
</attribute>
<attribute name="userTable" required="true">
- <p>Name of the "users" table, which must contain columns named
- by the <code>userNameCol</code> and <code>userCredCol</code>
- attributes.</p>
+ <p>The name of the table that contains one row for each
+ <em>username</em> to be recognized by Tomcat. This table must include
+ at least the columns named by the <code>userNameCol</code> and
+ <code>userCredCol</code> attributes.</p>
</attribute>
</attributes>
@@ -186,27 +191,35 @@
<attributes>
<attribute name="dataSourceName" required="true">
- <p>The name of the JNDI JDBC DataSource for this Realm.</p>
+ <p>The JNDI named JDBC DataSource for your database. If the DataSource
+ is local to the context, the name is relative to
+ <code>java:/comp/env</code>, and otherwise the name should match the
+ name used to define the global DataSource.</p>
</attribute>
- <attribute name="digest" required="false">
- <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>
- </attribute>
+ <attribute name="localDataSource" required="false">
+
+ <p>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 <code>false</code>: use a
+ global DataSource.</p>
+
+ </attribute>
+
<attribute name="roleNameCol" required="true">
<p>Name of the column, in the "user roles" table, which contains
a role name assigned to the corresponding user.</p>
</attribute>
<attribute name="userCredCol" required="true">
- <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>
+ <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>
</attribute>
<attribute name="userNameCol" required="true">
@@ -215,15 +228,17 @@
</attribute>
<attribute name="userRoleTable" required="true">
- <p>Name of the "user roles" table, which must contain columns
- named by the <code>userNameCol</code> and <code>roleNameCol</code>
- attributes.</p>
+ <p>The name of the table that contains one row for each <em>role</em>
+ assigned to a particular <em>username</em>. This table must include at
+ least the columns named by the <code>userNameCol</code> and
+ <code>roleNameCol</code> attributes.</p>
</attribute>
<attribute name="userTable" required="true">
- <p>Name of the "users" table, which must contain columns named
- by the <code>userNameCol</code> and <code>userCredCol</code>
- attributes.</p>
+ <p>The name of the table that contains one row for each
+ <em>username</em> to be recognized by Tomcat. This table must include
+ at least the columns named by the <code>userNameCol</code> and
+ <code>userCredCol</code> attributes.</p>
</attribute>
</attributes>
@@ -307,7 +322,8 @@
<attribute name="contextFactory" required="false">
<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>
+ assumes that the standard JNDI LDAP provider will be utilized
+ (<code>com.sun.jndi.ldap.LdapCtxFactory</code>).</p>
</attribute>
<attribute name="derefAliases" required="false">
@@ -338,12 +354,13 @@
</attribute>
<attribute name="roleSearch" required="false">
- <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>
+ <p>The LDAP filter expression used for performing role searches,
+ following the syntax supported by the
+ <code>java.text.MessageFormat</code> class. 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>
</attribute>
@@ -357,30 +374,32 @@
<attribute name="userBase" required="false">
<p>The base element for user searches performed using the
- <code>userSearch</code> expression. Not used if you are using
+ <code>userSearch</code> expression. If not specified, the top level
+ element in the directory context will be used. Not used if you are using
the <code>userPattern</code> expression.</p>
</attribute>
<attribute name="userPassword" required="false">
- <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
+ <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>
+ corresponding attribute for comparison to the value specified by the
+ user being authenticated. If the <code>digest</code> 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 <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>
</attribute>
<attribute name="userPattern" required="false">
- <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>
+ <p>Pattern for the distinguished name (DN) of the user's directory
+ entry, following the syntax supported by the
+ <code>java.text.MessageFormat</code> class. 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>
</attribute>
@@ -470,6 +489,65 @@
Memory Based Realm component.</p>
+ <h3>User Database Realm (org.apache.catalina.realm.UserDatabaseRealm)</h3>
+
+ <p>The <strong>User Database Realm</strong> is Realm implementation
+ that is based on an implementation of the <code>UserDatabase</code>
+ interface that is made available through the global JNDI resources
+ configured for this Tomcat instance.</p>
+
+ <p>The User Database Realm implementation supports the following
+ additional attributes:</p>
+
+ <attributes>
+
+ <attribute name="resourceName" required="true">
+ <p>The global JNDI name of the <code>UserDatabase</code> resource
+ used by this Realm.</p>
+ </attribute>
+
+ </attributes>
+
+ <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
+ information on setting up container managed security using the
+ UserDatabase Realm component.</p>
+
+ <h3>JAAS Realm (org.apache.catalina.realm.JAASRealm)</h3>
+
+ <p>The JAAS Realm implementation supports the following additional
+ attributes:</p>
+
+ <attributes>
+ <attribute name="appName" required="true">
+ <p>The name of the application as configured in your login configuration
+ file (<a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/LoginConfigFile.html">
+ JAAS LoginConfig</a>).</p>
+ </attribute>
+
+ <attribute name="userClassNames" required="true">
+ <p>A comma-seperated list of the names of the classes that you have made
+ for your user <code>Principals</code>.</p>
+ </attribute>
+
+ <attribute name="roleClassNames" required="false">
+ <p>A comma-seperated list of the names of the classes that you have made
+ for your role <code>Principals</code>.</p>
+ </attribute>
+
+ <attribute name="useContextClassLoader" required="false">
+ <p>Instructs JAASRealm to use the context class loader for loading the
+ user-specified <code>LoginModule</code> class and associated
+ <code>Principal</code> classes. The default value is <code>true</code>,
+ which is backwards-compatible with the way Tomcat 4 works. To load
+ classes using the container's classloader, specify <code>false</code>.
+ </p>
+ </attribute>
+
+ </attributes>
+
+ <p>See the <a href="../realm-howto.html">Container-Managed Security
+ Guide</a> for more information on setting up container managed security
+ using the JASS Realm component.</p>
</subsection>
Modified: tomcat/container/tc5.5.x/webapps/docs/realm-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/container/tc5.5.x/webapps/docs/realm-howto.xml?view=diff&rev=469024&r1=469023&r2=469024
==============================================================================
--- tomcat/container/tc5.5.x/webapps/docs/realm-howto.xml (original)
+++ tomcat/container/tc5.5.x/webapps/docs/realm-howto.xml Sun Oct 29 15:45:16 2006
@@ -39,6 +39,7 @@
<a href="#JNDIRealm">JNDIRealm</a><br />
<a href="#MemoryRealm">MemoryRealm</a><br />
<a href="#JAASRealm">JAASRealm</a><br />
+<a href="#UserDatabaseRealm">UserDatabaseRealm</a><br />
</blockquote>
</p>
@@ -336,76 +337,11 @@
<h3>Realm Element Attributes</h3>
-<p>To configure JDBCRealm, you will create a <code><Realm></code>
+<p>To configure a JDBCRealm, you must create a <code><Realm></code>
element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
-as described <a href="#Configuring a Realm">above</a>. The following
-attributes are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
- </attribute>
-
- <attribute name="connectionName" required="true">
- <p>The database username used to establish a JDBC connection.</p>
- </attribute>
-
- <attribute name="connectionPassword" required="true">
- <p>The database password used to establish a JDBC connection.</p>
- </attribute>
-
- <attribute name="connectionURL" required="true">
- <p>The database URL used to establish a JDBC connection.</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm used to store passwords in non-plaintext formats.
- Valid values are those accepted for the algorithm name by the
- <code>java.security.MessageDigest</code> class. See
- <a href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified, passwords are stored in clear text.</p>
- </attribute>
-
- <attribute name="driverName" required="true">
- <p>The fully qualified Java class name of the JDBC driver to be used.
- Consult the documentation for your JDBC driver for the appropriate
- value.</p>
- </attribute>
-
- <attribute name="roleNameCol" required="true">
- <p>The name of the column, in the <em>user roles</em> table, that
- contains the name of a role assigned to this user.</p>
- </attribute>
-
- <attribute name="userCredCol" required="true">
- <p>The name of the column, in the <em>users</em> table, that contains
- the password for this user (either in clear text, or digested if the
- <code>digest</code> attribute is set).</p>
- </attribute>
-
- <attribute name="userNameCol" required="true">
- <p>The name of the column, in the <em>users</em> and <em>user roles</em>
- tables, that contains the username of this user.</p>
- </attribute>
-
- <attribute name="userRoleTable" required="true">
- <p>The name of the table that contains one row for each <em>role</em>
- assigned to a particular <em>username</em>. This table must include at
- least the columns named by the <code>userNameCol</code> and
- <code>roleNameCol</code> attributes.</p>
- </attribute>
-
- <attribute name="userTable" required="true">
- <p>The name of the table that contains one row for each <em>username</em>
- to be recognized by Tomcat. This table must include at least the columns
- named by the <code>userNameCol</code> and <code>userCredCol</code>
- attributes.</p>
- </attribute>
-
-</attributes>
+as described <a href="#Configuring a Realm">above</a>. The attributes supported
+by this Realm are listed in the <a href="config/realm.html">Realm configuration
+documentation</a>.</p>
<h3>Example</h3>
@@ -514,72 +450,11 @@
<h3>Realm Element Attributes</h3>
-<p>To configure DataSourceRealm, you will create a <code><Realm></code>
+<p>To configure a DataSourceRealm, you must create a <code><Realm></code>
element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
-as described <a href="#Configuring a Realm">above</a>. The following
-attributes are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.DataSourceRealm</code>" here.</p>
- </attribute>
-
- <attribute name="dataSourceName" required="true">
- <p>The JNDI named JDBC DataSource for your database. If the DataSource is
- local to the context, the name is relative to <code>java:/comp/env</code>,
- and otherwise the name should match the name used to define the global
- DataSource.</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm used to store passwords in non-plaintext formats.
- Valid values are those accepted for the algorithm name by the
- <code>java.security.MessageDigest</code> class. See
- <a href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified, passwords are stored in clear text.</p>
- </attribute>
-
- <attribute name="localDataSource" required="false">
- <p>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 <code>false</code>: use a
- global DataSource.</p>
- </attribute>
-
- <attribute name="roleNameCol" required="true">
- <p>The name of the column, in the <em>user roles</em> table, that
- contains the name of a role assigned to this user.</p>
- </attribute>
-
- <attribute name="userCredCol" required="true">
- <p>The name of the column, in the <em>users</em> table, that contains
- the password for this user (either in clear text, or digested if the
- <code>digest</code> attribute is set).</p>
- </attribute>
-
- <attribute name="userNameCol" required="true">
- <p>The name of the column, in the <em>users</em> and <em>user roles</em>
- tables, that contains the username of this user.</p>
- </attribute>
-
- <attribute name="userRoleTable" required="true">
- <p>The name of the table that contains one row for each <em>role</em>
- assigned to a particular <em>username</em>. This table must include at
- least the columns named by the <code>userNameCol</code> and
- <code>roleNameCol</code> attributes.</p>
- </attribute>
-
- <attribute name="userTable" required="true">
- <p>The name of the table that contains one row for each <em>username</em>
- to be recognized by Tomcat. This table must include at least the columns
- named by the <code>userNameCol</code> and <code>userCredCol</code>
- attributes.</p>
- </attribute>
-
-</attributes>
+as described <a href="#Configuring a Realm">above</a>. The attributes supported
+by this Realm are listed in the <a href="config/realm.html">Realm configuration
+documentation</a>.</p>
<h3>Example</h3>
@@ -825,160 +700,11 @@
<h3>Realm Element Attributes</h3>
-<p>To configure JNDIRealm, you will create a <code><Realm></code>
+<p>To configure a JNDIRealm, you must create a <code><Realm></code>
element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
-as described <a href="#Configuring a Realm">above</a>. The following
-attributes are supported by this implementation:</p>
-
-<attributes>
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.JNDIRealm</code>" here.</p>
- </attribute>
-
-
- <attribute name="connectionName" required="false">
- <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>
- </attribute>
-
- <attribute name="connectionPassword" required="false">
- <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>
- </attribute>
-
- <attribute name="connectionURL" required="true">
- <p>The connection URL to be passed to the JNDI driver when
- establishing a connection to the directory.</p>
- </attribute>
-
- <attribute name="contextFactory" required="false">
- <p>The fully qualified Java class name of the JNDI context
- factory to be used for this connection. By default, the standard
- JNDI LDAP provider is used
- (<code>com.sun.jndi.ldap.LdapCtxFactory</code>).</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm to apply to the plaintext password offered
- by the user before comparing it with the value retrieved from the
- directory. Valid values are those accepted for the algorithm name
- by the <code>java.security.MessageDigest</code> class. See <a
- href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified the plaintext password is assumed to
- be retrieved. Not required unless <code>userPassword</code> is
- specified</p>
- </attribute>
-
- <attribute name="roleBase" required="false">
- <p>The base directory entry for performing role searches. If
- not specified, the top level element in the directory context
- will be used.</p>
- </attribute>
-
- <attribute name="roleName" required="false">
- <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>
- </attribute>
-
- <attribute name="roleSearch" required="false">
- <p>The LDAP filter expression used for performing role
- searches, following the syntax supported by the
- <code>java.text.MessageFormat</code> class. 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>
- </attribute>
-
- <attribute name="roleSubtree" required="false">
- <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>
- </attribute>
-
- <attribute name="userBase" required="false">
- <p>The base element for user searches performed using the
- <code>userSearch</code> expression. If not specified, the top
- level element in the directory context will be used. Not used
- if you are using the <code>userPattern</code> expression.</p>
- </attribute>
-
- <attribute name="userPassword" required="false">
- <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 the <code>digest</code>
- 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
- <strong>not</strong> specify this value, JNDIRealm will
- attempt a simple bind to the directory using the DN of the
- user's entry and password specified by the user, with a
- successful bind being interpreted as an authenticated
- user.</p>
- </attribute>
-
- <attribute name="userPattern" required="false">
- <p>A pattern for the distinguished name (DN) of the user's
- directory entry, following the syntax supported by the
- <code>java.text.MessageFormat</code> class 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>
- </attribute>
-
- <attribute name="userRoleName" required="false">
- <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>
- </attribute>
-
- <attribute name="userSearch" required="false">
- <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>
- </attribute>
-
- <attribute name="userSubtree" required="false">
- <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>
- </attribute>
-
-</attributes>
+as described <a href="#Configuring a Realm">above</a>. The attributes supported
+by this Realm are listed in the <a href="config/realm.html">Realm configuration
+documentation</a>.</p>
<h3>Example</h3>
@@ -1181,35 +907,11 @@
<h3>Realm Element Attributes</h3>
-<p>To configure MemoryRealm, you will create a <code><Realm></code>
+<p>To configure a MemoryRealm, you must create a <code><Realm></code>
element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
-as described <a href="#Configuring a Realm">above</a>. The following
-attributes are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.MemoryRealm</code>" here.</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm used to store passwords in non-plaintext formats.
- Valid values are those accepted for the algorithm name by the
- <code>java.security.MessageDigest</code> class. See
- <a href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified, passwords are stored in clear text.</p>
- </attribute>
-
- <attribute name="pathname" required="false">
- <p>Absolute or relative (to $CATALINA_HOME) pathname of the XML document
- containing our valid usernames, passwords, and roles. See below for more
- information on the format of this file. If not specified, the value
- <code>conf/tomcat-users.xml</code> is used.</p>
- </attribute>
-
-</attributes>
+as described <a href="#Configuring a Realm">above</a>. The attributes supported
+by this Realm are listed in the <a href="config/realm.html">Realm configuration
+documentation</a>.</p>
<h3>User File Format</h3>
@@ -1229,9 +931,7 @@
<h3>Example</h3>
-<p>The default installation of Tomcat 5 is configured with a MemoryRealm
-nested inside the <code><Engine></code> element, so that it applies
-to all virtual hosts and web applications. The default contents of the
+<p>The default contents of the
<code>conf/tomcat-users.xml</code> file is:</p>
<source>
<tomcat-users>
@@ -1263,6 +963,32 @@
provide any built-in capabilities to maintain users and roles.</li>
</ul>
+</subsection>
+
+
+<subsection name="UserDatabaseRealm">
+
+<h3>Introduction</h3>
+
+<p><strong>UserDatabaseRealm</strong> is an implementation of the
+Tomcat <code>Realm</code> interface. Information about all users, and their
+corresponding roles, is obtained from a JNDI resource that implements the
+<code>UserDatabase</code> interface.</p>
+
+<h3>Realm Element Attributes</h3>
+
+<p>To configure a UserDatabaseRealm, you must create a <code><Realm></code>
+element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
+as described <a href="#Configuring a Realm">above</a>. The attributes supported
+by this Realm are listed in the <a href="config/realm.html">Realm configuration
+documentation</a>.</p>
+
+<h3>Example</h3>
+
+<p>The default installation of Tomcat 5 is configured with a
+UserDatabaseRealm nested inside the <code><Engine></code> element, so that
+it applies to all virtual hosts and web applications. This realm uses the
+same <code>tomcat-users.xml</code> as the MemoryRealm.</p>
</subsection>
@@ -1324,45 +1050,15 @@
<li>Configure the JAASRealm module in your server.xml </li>
<li>Restart Tomcat 5 if it is already running.</li>
</ol>
- <h3>Realm Element Attributes</h3>
- <p>To configure JAASRealm as for step 6 above, you create
-a <code><Realm></code> element and nest it in your
-<code>$CATALINA_HOME/conf/server.xml</code>
-file within your <code><Engine></code> node. The following attributes
-are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.JAASRealm</code>" here.</p>
- </attribute>
-
- <attribute name="appName" required="true">
- <p>The name of the application as configured in your login configuration file
- (<a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS LoginConfig</a>).</p>
- </attribute>
-
- <attribute name="userClassNames" required="true">
- <p>A comma-seperated list of the names of the classes that you have made
- for your user <code>Principals</code>.</p>
- </attribute>
-
- <attribute name="roleClassNames" required="false">
- <p>A comma-seperated list of the names of the classes that you have made
- for your role <code>Principals</code>.</p>
- </attribute>
-
- <attribute name="useContextClassLoader" required="false">
- <p>Instructs JAASRealm to use the context class loader for loading the user-specified
- <code>LoginModule</code> class and associated <code>Principal</code> classes. The
- default value is <code>true</code>, which is backwards-compatible with the way
- Tomcat 4 works. To load classes using the container's classloader, specify
- <code>false</code>.</p>
- </attribute>
-</attributes>
+
+<h3>Realm Element Attributes</h3>
+
+<p>To configure a JAASRealm, you must create a <code><Realm></code>
+element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
+as described <a href="#Configuring a Realm">above</a>. The attributes supported
+by this Realm are listed in the <a href="config/realm.html">Realm configuration
+documentation</a>.</p>
<h3>Example</h3>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org