source: nutchez-0.1/tomcat/webapps/docs/config/realm.html @ 104

Last change on this file since 104 was 66, checked in by waue, 15 years ago

NutchEz - an easy way to nutch
File size: 31.0 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Realm Component</title><meta value="Craig R. McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2    The Apache Tomcat Servlet/JSP Container
3  " align="right" src="../images/tomcat.gif"></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 border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><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><p><strong>Global Settings</strong></p><ul><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat Configuration Reference</h1><h2>The Realm Component</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/realm.html"><img alt="Printer Friendly Version" border="0" src="../images/printer.gif"><br>print-friendly<br>version
4                    </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
5
6  <p>A <strong>Realm</strong> element represents a "database" of usernames,
7  passwords, and <em>roles</em> (similar to Unix <em>groups</em>) assigned
8  to those users.  Different implementations of Realm allow Catalina to be
9  integrated into environments where such authentication information is already
10  being created and maintained, and then utilize that information to implement
11  <em>Container Managed Security</em> as described in the Servlet
12  Specification.</p>
13
14  <p>You may nest a Realm inside any Catalina container
15  <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
16  <a href="context.html">Context</a>).  In addition, Realms associated with
17  an Engine or a Host are automatically inherited by lower-level
18  containers, unless explicitly overridden.</p>
19
20  <p>For more in-depth information about container managed security in web
21  applications, as well as more information on configuring and using the
22  standard realm component implementations, please see the
23  <a href="../realm-howto.html">Container-Managed Security Guide</a>.
24  </p>
25
26    <blockquote><em>
27    <p>The description below uses the variable name $CATALINA_BASE to refer the
28    base directory against which most relative paths are resolved. If you have
29    not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE
30    directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
31    the directory into which you have installed Tomcat 6.</p>
32    </em></blockquote>
33
34</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
35
36  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Common Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>
37
38    <p>All implementations of <strong>Realm</strong>
39    support the following attributes:</p>
40
41    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left">
42        <p>Java class name of the implementation to use.  This class must
43        implement the <code>org.apache.catalina.Realm</code> interface.</p>
44      </td></tr></table>
45
46  </blockquote></td></tr></table>
47
48
49  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Standard Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote>
50
51    <p>Unlike most Catalina components, there are several standard
52    <strong>Realm</strong> implementations available.  As a result,
53    the <code>className</code> attribute MUST be used to select the
54    implementation you wish to use.</p>
55
56    <h3>JDBC Database Realm (org.apache.catalina.realm.JDBCRealm)</h3>
57
58    <p>The <strong>JDBC Database Realm</strong> connects Catalina to
59    a relational database, accessed through an appropriate JDBC driver,
60    to perform lookups of usernames, passwords, and their associated
61    roles.  Because the lookup is done each time that it is required,
62    changes to the database will be immediately reflected in the
63    information used to authenticate new logins.</p>
64
65    <p>A rich set of additional attributes lets you configure the required
66    connection to the underlying database, as well as the table and
67    column names used to retrieve the required information:</p>
68
69    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>connectionName</code></strong></td><td valign="center" align="left">
70        <p>The database username to use when establishing the JDBC
71        connection.</p>
72      </td></tr><tr><td valign="center" align="left"><strong><code>connectionPassword</code></strong></td><td valign="center" align="left">
73        <p>The database password to use when establishing the JDBC
74        connection.</p>
75      </td></tr><tr><td valign="center" align="left"><strong><code>connectionURL</code></strong></td><td valign="center" align="left">
76        <p>The connection URL to be passed to the JDBC driver when
77        establishing a database connection.</p>
78      </td></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left">
79        <p>The name of the <code>MessageDigest</code> algorithm used
80        to encode user passwords stored in the database.  If not specified,
81        user passwords are assumed to be stored in clear-text.</p>
82      </td></tr><tr><td valign="center" align="left"><code>digestEncoding</code></td><td valign="center" align="left">
83        <p>The charset for encoding digests.  If not specified, the platform
84        default will be used.</p>
85      </td></tr><tr><td valign="center" align="left"><strong><code>driverName</code></strong></td><td valign="center" align="left">
86        <p>Fully qualified Java class name of the JDBC driver to be
87        used to connect to the authentication database.</p>
88      </td></tr><tr><td valign="center" align="left"><strong><code>roleNameCol</code></strong></td><td valign="center" align="left">
89        <p>Name of the column, in the "user roles" table, which contains
90        a role name assigned to the corresponding user.</p>
91      </td></tr><tr><td valign="center" align="left"><strong><code>userCredCol</code></strong></td><td valign="center" align="left">
92        <p>Name of the column, in the "users" table, which contains
93        the user's credentials (i.e. password(.  If a value for the
94        <code>digest</code> attribute is specified, this component
95        will assume that the passwords have been encoded with the
96        specified algorithm.  Otherwise, they will be assumed to be
97        in clear text.</p>
98      </td></tr><tr><td valign="center" align="left"><strong><code>userNameCol</code></strong></td><td valign="center" align="left">
99        <p>Name of the column, in the "users" and "user roles" table,
100        that contains the user's username.</p>
101      </td></tr><tr><td valign="center" align="left"><strong><code>userRoleTable</code></strong></td><td valign="center" align="left">
102        <p>Name of the "user roles" table, which must contain columns
103        named by the <code>userNameCol</code> and <code>roleNameCol</code>
104        attributes.</p>
105      </td></tr><tr><td valign="center" align="left"><strong><code>userTable</code></strong></td><td valign="center" align="left">
106        <p>Name of the "users" table, which must contain columns named
107        by the <code>userNameCol</code> and <code>userCredCol</code>
108        attributes.</p>
109      </td></tr></table>
110
111    <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
112    information on setting up container managed security using the
113    JDBC Database Realm component.</p>
114
115
116    <h3>
117      DataSource Database Realm (org.apache.catalina.realm.DataSourceRealm)
118    </h3>
119
120    <p>The <strong>DataSource Database Realm</strong> connects Catalina to
121    a relational database, accessed through a JNDI named JDBC DataSource
122    to perform lookups of usernames, passwords, and their associated
123    roles.  Because the lookup is done each time that it is required,
124    changes to the database will be immediately reflected in the
125    information used to authenticate new logins.</p>
126
127    <p>The JDBC Realm uses a single db connection. This requires that
128    realm based authentication be synchronized, i.e. only one authentication
129    can be done at a time. This could be a bottleneck for applications
130    with high volumes of realm based authentications.</p>
131
132    <p>The DataSource Database Realm supports simultaneous realm based
133    authentications and allows the underlying JDBC DataSource to
134    handle optimizations like database connection pooling.</p>
135
136    <p>A rich set of additional attributes lets you configure the name
137    of the JNDI JDBC DataSource, as well as the table and
138    column names used to retrieve the required information:</p>
139
140    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>dataSourceName</code></strong></td><td valign="center" align="left">
141        <p>The name of the JNDI JDBC DataSource for this Realm.</p>
142      </td></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left">
143        <p>The name of the <code>MessageDigest</code> algorithm used
144        to encode user passwords stored in the database.  If not specified,
145        user passwords are assumed to be stored in clear-text.</p>
146      </td></tr><tr><td valign="center" align="left"><code>localDataSource</code></td><td valign="center" align="left">
147        <p>When the realm is nested inside a Context element, this allows the
148        realm to use a DataSource defined for the Context rather than a global
149        DataSource.  If not specified, the default is <code>false</code>: use a
150        global DataSource.</p>
151      </td></tr><tr><td valign="center" align="left"><strong><code>roleNameCol</code></strong></td><td valign="center" align="left">
152        <p>Name of the column, in the "user roles" table, which contains
153        a role name assigned to the corresponding user.</p>
154      </td></tr><tr><td valign="center" align="left"><strong><code>userCredCol</code></strong></td><td valign="center" align="left">
155        <p>Name of the column, in the "users" table, which contains
156        the user's credentials (i.e. password(.  If a value for the
157        <code>digest</code> attribute is specified, this component
158        will assume that the passwords have been encoded with the
159        specified algorithm.  Otherwise, they will be assumed to be
160        in clear text.</p>
161      </td></tr><tr><td valign="center" align="left"><strong><code>userNameCol</code></strong></td><td valign="center" align="left">
162        <p>Name of the column, in the "users" and "user roles" table,
163        that contains the user's username.</p>
164      </td></tr><tr><td valign="center" align="left"><strong><code>userRoleTable</code></strong></td><td valign="center" align="left">
165        <p>Name of the "user roles" table, which must contain columns
166        named by the <code>userNameCol</code> and <code>roleNameCol</code>
167        attributes.</p>
168      </td></tr><tr><td valign="center" align="left"><strong><code>userTable</code></strong></td><td valign="center" align="left">
169        <p>Name of the "users" table, which must contain columns named
170        by the <code>userNameCol</code> and <code>userCredCol</code>
171        attributes.</p>
172      </td></tr></table>
173
174    <p>See the <a href="../realm-howto.html#DataSourceRealm">
175    DataSource Realm HOW-TO</a> for more information on setting up container
176    managed security using the DataSource Database Realm component.</p>
177
178
179    <h3>JNDI Directory Realm (org.apache.catalina.realm.JNDIRealm)</h3>
180
181
182    <p>The <strong>JNDI Directory Realm</strong> connects Catalina to
183    an LDAP Directory, accessed through an appropriate JNDI driver,
184    that stores usernames, passwords, and their associated
185    roles. Changes to the directory are immediately reflected in the
186    information used to authenticate new logins.</p>
187
188
189    <p>The directory realm supports a variety of approaches to using
190    LDAP for authentication:</p>
191
192    <ul>
193    <li>The realm can either use a pattern to determine the
194    distinguished name (DN) of the user's directory entry, or search
195    the directory to locate that entry.
196    </li>
197
198    <li>The realm can authenticate the user either by binding to the
199    directory with the DN of the user's entry and the password
200    presented by the user, or by retrieving the password from the
201    user's entry and performing a comparison locally.
202    </li>
203
204    <li>Roles may be represented in the directory as explicit entries
205    found by a directory search (e.g. group entries of which the user
206    is a member), as the values of an attribute in the user's entry,
207    or both.
208    </li>
209    </ul>
210
211    <p> A rich set of additional attributes lets you configure the
212    required behaviour as well as the connection to the underlying
213    directory and the element and attribute names used to retrieve
214    information from the directory:</p>
215
216    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>alternateURL</code></td><td valign="center" align="left">
217         <p>If a socket connection can not be made to the provider at
218         the <code>connectionURL</code> an attempt will be made to use the
219         <code>alternateURL</code>.</p>
220       </td></tr><tr><td valign="center" align="left"><code>authentication</code></td><td valign="center" align="left">
221         <p>A string specifying the type of authentication to use.
222         "none", "simple", "strong" or a provider specific definition
223         can be used. If no value is given the providers default is used.</p>
224       </td></tr><tr><td valign="center" align="left"><code>connectionName</code></td><td valign="center" align="left">
225        <p>The directory username to use when establishing a
226        connection to the directory for LDAP search operations. If not
227        specified an anonymous connection is made, which is often
228        sufficient unless you specify the <code>userPassword</code>
229        property.</p>
230      </td></tr><tr><td valign="center" align="left"><code>connectionPassword</code></td><td valign="center" align="left">
231        <p>The directory password to use when establishing a
232        connection to the directory for LDAP search operations. If not
233        specified an anonymous connection is made, which is often
234        sufficient unless you specify the <code>userPassword</code>
235        property.</p>
236      </td></tr><tr><td valign="center" align="left"><strong><code>connectionURL</code></strong></td><td valign="center" align="left">
237        <p>The connection URL to be passed to the JNDI driver when
238        establishing a connection to the directory.</p>
239      </td></tr><tr><td valign="center" align="left"><code>contextFactory</code></td><td valign="center" align="left">
240        <p>Fully qualified Java class name of the factory class used
241        to acquire our JNDI <code>InitialContext</code>.  By default,
242        assumes that the standard JNDI LDAP provider will be utilized.</p>
243      </td></tr><tr><td valign="center" align="left"><code>derefAliases</code></td><td valign="center" align="left">
244        <p>A string specifying how aliases are to be dereferenced during
245        search operations. The allowed values are "always", "never",
246        "finding" and "searching". If not specified, "always" is used.</p>
247      </td></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left">
248        <p>The digest algorithm to apply to the plaintext password offered
249        by the user before comparing it with the value retrieved from the
250        directory.  Valid values are those accepted for the algorithm name
251        by the <code>java.security.MessageDigest</code> class. If not
252        specified the plaintext password is assumed to be retrieved. Not
253        required unless <code>userPassword</code> is specified</p>
254      </td></tr><tr><td valign="center" align="left"><code>protocol</code></td><td valign="center" align="left">
255         <p>A string specifying the security protocol to use. If not given
256         the providers default is used.</p>
257      </td></tr><tr><td valign="center" align="left"><code>roleBase</code></td><td valign="center" align="left">
258        <p>The base directory entry for performing role searches. If
259        not specified the top-level element in the directory context
260        will be used.</p>
261      </td></tr><tr><td valign="center" align="left"><code>roleName</code></td><td valign="center" align="left">
262        <p>The name of the attribute that contains role names in the
263        directory entries found by a role search. In addition you can
264        use the <code>userRoleName</code> property to specify the name
265        of an attribute, in the user's entry, containing additional
266        role names.  If <code>roleName</code> is not specified a role
267        search does not take place, and roles are taken only from the
268        user's entry.</p>
269      </td></tr><tr><td valign="center" align="left"><code>roleSearch</code></td><td valign="center" align="left">
270        <p>The LDAP filter expression used for performing role
271        searches.  Use <code>{0}</code> to substitute the
272        distinguished name (DN) of the user, and/or <code>{1}</code> to
273        substitute the username. If not specified a role search does
274        not take place and roles are taken only from the attribute in
275        the user's entry specified by the <code>userRoleName</code>
276        property.</p>
277      </td></tr><tr><td valign="center" align="left"><code>roleSubtree</code></td><td valign="center" align="left">
278        <p>Set to <code>true</code> if you want to search the entire
279        subtree of the element specified by the <code>roleBase</code>
280        property for role entries associated with the user. The
281        default value of <code>false</code> causes only the top level
282        to be searched.</p>
283      </td></tr><tr><td valign="center" align="left"><code>userBase</code></td><td valign="center" align="left">
284        <p>The base element for user searches performed using the
285        <code>userSearch</code> expression.  Not used if you are using
286        the <code>userPattern</code> expression.</p>
287      </td></tr><tr><td valign="center" align="left"><code>userPassword</code></td><td valign="center" align="left">
288        <p>Name of the attribute in the user's entry containing the
289        user's password.  If you specify this value, JNDIRealm will
290        bind to the directory using the values specified by
291        <code>connectionName</code> and
292        <code>connectionPassword</code> properties, and retrieve the
293        corresponding attribute for comparison to the value specified
294        by the user being authenticated.  If you do
295        <strong>not</strong> specify this value, JNDIRealm will
296        attempt a simple bind to the directory using the DN of the
297        user's entry and the password presented by the user, with a
298        successful bind being interpreted as an authenticated
299        user.</p>
300      </td></tr><tr><td valign="center" align="left"><code>userPattern</code></td><td valign="center" align="left">
301        <p>Pattern for the distinguished name (DN) of the user's
302        directory entry, with <code>{0}</code> marking where the
303        actual username should be inserted. You can use this property
304        instead of <code>userSearch</code>, <code>userSubtree</code>
305        and <code>userBase</code> when the distinguished name contains
306        the username and is otherwise the same for all users.</p>
307      </td></tr><tr><td valign="center" align="left"><code>userRoleName</code></td><td valign="center" align="left">
308        <p>The name of an attribute in the user's directory entry
309        containing zero or more values for the names of roles assigned
310        to this user.  In addition you can use the
311        <code>roleName</code> property to specify the name of an
312        attribute to be retrieved from individual role entries found
313        by searching the directory. If <code>userRoleName</code> is
314        not specified all the roles for a user derive from the role
315        search.</p>
316      </td></tr><tr><td valign="center" align="left"><code>userSearch</code></td><td valign="center" align="left">
317        <p>The LDAP filter expression to use when searching for a
318        user's directory entry, with <code>{0}</code> marking where
319        the actual username should be inserted.  Use this property
320        (along with the <code>userBase</code> and
321        <code>userSubtree</code> properties) instead of
322        <code>userPattern</code> to search the directory for the
323        user's entry.</p>
324      </td></tr><tr><td valign="center" align="left"><code>userSubtree</code></td><td valign="center" align="left">
325        <p>Set to <code>true</code> if you want to search the entire
326        subtree of the element specified by the <code>userBase</code>
327        property for the user's entry. The default value of
328        <code>false</code> causes only the top level to be searched.
329        Not used if you are using the <code>userPattern</code>
330        expression.</p>
331      </td></tr></table>
332
333    <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
334    information on setting up container managed security using the
335    JNDI Directory Realm component.</p>
336
337
338    <h3>Memory Based Realm (org.apache.catalina.realm.MemoryRealm)</h3>
339
340    <p>The <strong>Memory Based Realm</strong> is a simple Realm implementation
341    that reads user information from an XML format, and represents it as a
342    collection of Java objects in memory.  This implementation is intended
343    solely to get up and running with container managed security - it is NOT
344    intended for production use.  As such, there are no mechanisms for
345    updating the in-memory collection of users when the content of the
346    underlying data file is changed.</p>
347
348    <p>The Memory Based Realm implementation supports the following
349    additional attributes:</p>
350
351    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left">
352        <p>The digest algorithm used to store passwords in non-plaintext
353        formats. Valid values are those accepted for the algorithm name by the
354        <code>java.security.MessageDigest</code> class. If not specified,
355        passwords are stored in clear text.</p>
356      </td></tr><tr><td valign="center" align="left"><code>pathname</code></td><td valign="center" align="left">
357        <p>Absolute or relative (to $CATALINA_BASE) pathname to the XML file
358        containing our user information.  See below for details on the
359        XML element format required.  If no pathname is specified, the
360        default value is <code>conf/tomcat-users.xml</code>.</p>
361      </td></tr></table>
362
363    <p>The XML document referenced by the <code>pathname</code> attribute must
364    conform to the following requirements:</p>
365    <ul>
366    <li>The root (outer) element must be <code>&lt;tomcat-users&gt;</code>.
367        </li>
368    <li>Each authorized user must be represented by a single XML element
369        <code>&lt;user&gt;</code>, nested inside the root element.</li>
370    <li>Each <code>&lt;user&gt;</code> element must have the following
371        attributes:
372        <ul>
373        <li><strong>name</strong> - Username of this user (must be unique
374            within this file).</li>
375        <li><strong>password</strong> - Password of this user (in
376            clear text).</li>
377        <li><strong>roles</strong> - Comma-delimited list of the role names
378            assigned to this user.</li>
379        </ul></li>
380    </ul>
381
382    <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
383    information on setting up container managed security using the
384    Memory Based Realm component.</p>
385
386    <h3>JAAS Realm (org.apache.catalina.realm.JAASRealm)</h3>
387
388    <p><strong>JAASRealm</strong> is an implementation of the Tomcat 6
389    <code>Realm</code> interface that authenticates users through the Java
390    Authentication &amp; Authorization Service (JAAS) framework which is now
391    provided as part of the standard J2SE API.</p>
392
393    <p>Using JAASRealm gives the developer the ability to combine practically
394    any conceivable security realm with Tomcat's CMA.</p>
395
396    <p>JAASRealm is prototype for Tomcat of the JAAS-based J2EE authentication
397    framework for J2EE v1.4, based on the <a href="http://www.jcp.org/en/jsr/detail?id=196">JCP Specification Request
398    196</a> to enhance container-managed security and promote 'pluggable'
399    authentication mechanisms whose implementations would be
400    container-independent.</p>
401
402    <p>Based on the JAAS login module and principal
403    (see <code>javax.security.auth.spi.LoginModule</code> and
404    <code>javax.security.Principal</code>), you can develop your own security
405    mechanism or wrap another third-party mechanism for integration with the CMA
406    as implemented by Tomcat.</p>
407
408    <p>The JAAS Realm implementation supports the following additional
409    attributes:</p>
410
411    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>appName</code></strong></td><td valign="center" align="left">
412       <p>The name of the application as configured in your login configuration
413       file
414       (<a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS LoginConfig</a>).</p>
415      </td></tr><tr><td valign="center" align="left"><strong><code>userClassNames</code></strong></td><td valign="center" align="left">
416        <p>A comma-seperated list of the names of the classes that you have made
417        for your user <code>Principals</code>.</p>
418      </td></tr><tr><td valign="center" align="left"><code>roleClassNames</code></td><td valign="center" align="left">
419        <p>A comma-seperated list of the names of the classes that you have made
420        for your role <code>Principals</code>.</p>
421      </td></tr><tr><td valign="center" align="left"><code>useContextClassLoader</code></td><td valign="center" align="left">
422        <p>Instructs JAASRealm to use the context class loader for loading the
423        user-specified <code>LoginModule</code> class and associated
424        <code>Principal</code> classes. The default value is <code>true</code>,
425        which is backwards-compatible with the way Tomcat 5 works. To load
426        classes using the container's classloader, specify
427        <code>false</code>.</p>
428      </td></tr></table>
429
430    <p>See the <a href="../realm-howto.html">Container-Managed Security
431    Guide</a> for more information on setting up container managed security
432    using the JAAS Realm component.</p>
433
434  </blockquote></td></tr></table>
435
436
437</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Nested Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
438
439  <p>No components may be nested inside a <strong>Realm</strong> element.</p>
440
441</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Special Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
442
443  <p>See <a href="host.html">Single Sign On</a> for information about
444  configuring Single Sign On support for a virtual host.</p>
445
446</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
447        Copyright &copy; 1999-2008, Apache Software Foundation
448        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.