source: nutchez-0.1/tomcat/webapps/docs/printer/realm-howto.html

Last change on this file was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 85.0 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Realm Configuration HOW-TO</title><meta value="Craig R. McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"><meta value="Yoav Shapira" name="author"><meta value="yoavs@apache.org" name="email"><meta value="Andrew R. Jaquith" name="author"><meta value="arjaquith@mindspring.com" 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><!--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 6.0</h1><h2>Realm Configuration HOW-TO</h2></td><td nowrap="true" valign="top" align="right"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
4
5<p>
6<a href="#Quick Start">Quick Start</a><br>
7<blockquote>
8<a href="#What is a Realm?">What is a Realm?</a><br>
9<a href="#Configuring a Realm">Configuring a Realm</a><br>
10</blockquote>
11<a href="#Common Features">Common Features</a><br>
12<blockquote>
13<a href="#Digested Passwords">Digested Passwords</a><br>
14<a href="#Example Application">Example Application</a><br>
15<a href="#Manager Application">Manager Application</a><br>
16<a href="#Realm Logging">Logging Within Realms</a><br>
17</blockquote>
18<a href="#Standard Realm Implementations">
19Standard Realm Implementations</a><br>
20<blockquote>
21<a href="#JDBCRealm">JDBCRealm</a><br>
22<a href="#DataSourceRealm">DataSourceRealm</a><br>
23<a href="#JNDIRealm">JNDIRealm</a><br>
24<a href="#MemoryRealm">MemoryRealm</a><br>
25<a href="#JAASRealm">JAASRealm</a><br>
26</blockquote>
27</p>
28
29</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Quick Start"><strong>Quick Start</strong></a></font></td></tr><tr><td><blockquote>
30
31<p>This document describes how to configure Tomcat to support <em>container
32managed security</em>, by connecting to an existing "database" of usernames,
33passwords, and user roles.  You only need to care about this if you are using
34a web application that includes one or more
35<code>&lt;security-constraint&gt;</code> elements, and a
36<code>&lt;login-config&gt;</code> element defining how users are required
37to authenticate themselves.  If you are not utilizing these features, you can
38safely skip this document.</p>
39
40<p>For fundamental background information about container managed security,
41see the <a href="http://java.sun.com/products/servlet/download.html">Servlet
42Specification (Version 2.4)</a>, Section 12.</p>
43
44<p>For information about utilizing the <em>Single Sign On</em> feature of
45Tomcat 6 (allowing a user to authenticate themselves once across the entire
46set of web applications associated with a virtual host), see
47<a href="../config/host.html#Single Sign On">here</a>.</p>
48
49</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
50
51
52<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="What is a Realm?"><strong>What is a Realm?</strong></a></font></td></tr><tr><td><blockquote>
53
54<p>A <strong>Realm</strong> is a "database" of usernames and passwords that
55identify valid users of a web application (or set of web applications), plus
56an enumeration of the list of <em>roles</em> associated with each valid user.
57You can think of roles as similar to <em>groups</em> in Unix-like operating
58systems, because access to specific web application resources is granted to
59all users possessing a particular role (rather than enumerating the list of
60associated usernames).  A particular user can have any number of roles
61associated with their username.</p>
62
63<p>Although the Servlet Specification describes a portable mechanism for
64applications to <em>declare</em> their security requirements (in the
65<code>web.xml</code> deployment descriptor), there is no portable API
66defining the interface between a servlet container and the associated user
67and role information.  In many cases, however, it is desireable to "connect"
68a servlet container to some existing authentication database or mechanism
69that already exists in the production environment.  Therefore, Tomcat 6
70defines a Java interface (<code>org.apache.catalina.Realm</code>) that
71can be implemented by "plug in" components to establish this connection.
72Five standard plug-ins are provided, supporting connections to various
73sources of authentication information:</p>
74<ul>
75<li><a href="#JDBCRealm">JDBCRealm</a> - Accesses authentication information
76    stored in a relational database, accessed via a JDBC driver.</li>
77<li><a href="#DataSourceRealm">DataSourceRealm</a> - Accesses authentication
78    information stored in a relational database, accessed via a named JNDI
79    JDBC DataSource.</li>
80<li><a href="#JNDIRealm">JNDIRealm</a> - Accesses authentication information
81    stored in an LDAP based directory server, accessed via a JNDI provider.
82    </li>
83<li><a href="#MemoryRealm">MemoryRealm</a> - Accesses authentication
84    information stored in an in-memory object collection, which is initialized
85    from an XML document (<code>conf/tomcat-users.xml</code>).</li>
86<li><a href="#JAASRealm">JAASRealm</a> - Accesses authentication information
87    through the Java Authentication &amp; Authorization Service (JAAS)
88    framework.</li>
89</ul>
90
91<p>It is also possible to write your own <code>Realm</code> implementation,
92and integrate it with Tomcat 6.  To do so, you need to:
93<ul>
94  <li>Implement <code>org.apache.catalina.Realm</code>,</li>
95  <li>Place your compiled realm in $CATALINA_HOME/lib,</li>
96  <li>Declare your realm as described in the "Configuring a Realm" section below,</li>
97  <li>Declare your realm to the <a href="mbeans-descriptor-howto.html">MBeans Descriptor</a>.</li>
98</ul>
99</p>
100
101</blockquote></td></tr></table>
102
103
104<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Configuring a Realm"><strong>Configuring a Realm</strong></a></font></td></tr><tr><td><blockquote>
105
106<p>Before getting into the details of the standard Realm implementations, it is
107important to understand, in general terms, how a Realm is configured.  In
108general, you will be adding an XML element to your <code>conf/server.xml</code>
109configuration file, that looks something like this:</p>
110
111<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
112&lt;Realm className="... class name for this implementation"
113       ... other attributes for this implementation .../&gt;
114</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
115
116<p>The <code>&lt;Realm&gt;</code> element can be nested inside any one of
117of the following <code>Container</code> elements.  The location of the
118Realm element has a direct impact on the "scope" of that Realm
119(i.e. which web applications will share the same authentication information):
120</p>
121<ul>
122<li><em>Inside an &lt;Engine&gt; element</em> - This Realm will be shared
123    across ALL web applications on ALL virtual hosts, UNLESS it is overridden
124    by a Realm element nested inside a subordinate <code>&lt;Host&gt;</code>
125    or <code>&lt;Context&gt;</code> element.</li>
126<li><em>Inside a &lt;Host&gt; element</em> - This Realm will be shared across
127    ALL web applications for THIS virtual host, UNLESS it is overridden
128    by a Realm element nested inside a subordinate <code>&lt;Context&gt;</code>
129    element.</li>
130<li><em>Inside a &lt;Context&gt; element</em> - This Realm will be used ONLY
131    for THIS web application.</li>
132</ul>
133
134
135</blockquote></td></tr></table>
136
137
138</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Common Features"><strong>Common Features</strong></a></font></td></tr><tr><td><blockquote>
139
140
141<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Digested Passwords"><strong>Digested Passwords</strong></a></font></td></tr><tr><td><blockquote>
142
143<p>For each of the standard <code>Realm</code> implementations, the
144user's password (by default) is stored in clear text.  In many
145environments, this is undesireable because casual observers of the
146authentication data can collect enough information to log on
147successfully, and impersonate other users.  To avoid this problem, the
148standard implementations support the concept of <em>digesting</em>
149user passwords.  This allows the stored version of the passwords to be
150encoded (in a form that is not easily reversible), but that the
151<code>Realm</code> implementation can still utilize for
152authentication.</p>
153
154<p>When a standard realm authenticates by retrieving the stored
155password and comparing it with the value presented by the user, you
156can select digested passwords by specifying the <code>digest</code>
157attribute on your <code>&lt;Realm&gt;</code> element.  The value for
158this attribute must be one of the digest algorithms supported by the
159<code>java.security.MessageDigest</code> class (SHA, MD2, or MD5).
160When you select this option, the contents of the password that is
161stored in the <code>Realm</code> must be the cleartext version of the
162password, as digested by the specified algorithm.</p>
163
164<p>When the <code>authenticate()</code> method of the Realm is called, the
165(cleartext) password specified by the user is itself digested by the same
166algorithm, and the result is compared with the value returned by the
167<code>Realm</code>.  An equal match implies that the cleartext version of the
168original password is the same as the one presented by the user, so that this
169user should be authorized.</p>
170
171<p>To calculate the digested value of a cleartext password, two convenience
172techniques are supported:</p>
173<ul>
174<li>If you are writing an application that needs to calculate digested
175    passwords dynamically, call the static <code>Digest()</code> method of the
176    <code>org.apache.catalina.realm.RealmBase</code> class, passing the
177    cleartext password and the digest algorithm name as arguments.  This
178    method will return the digested password.</li>
179<li>If you want to execute a command line utility to calculate the digested
180    password, simply execute
181<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
182java org.apache.catalina.realm.RealmBase \
183    -a {algorithm} {cleartext-password}
184</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
185    and the digested version of this cleartext password will be returned to
186    standard output.</li>
187</ul>
188
189<p>If using digested passwords with DIGEST authentication, the cleartext used
190   to generate the digest is different. In the examples above
191   <code>{cleartext-password}</code> must be replaced with
192   <code>{username}:{realm}:{cleartext-password}</code>. For example, in a
193   development environment this might take the form
194   <code>testUser:localhost:8080:testPassword</code>.</p>
195
196<p>To use either of the above techniques, the
197<code>$CATALINA_HOME/lib/catalina.jar</code> and
198<code>$CATALINA_HOME/bin/tomcat-juli.jar</code> files will need to be
199on your class path to make the <code>RealmBase</code> class available.
200</p>
201
202<p>Non-ASCII usernames and/or passwords are supported using
203<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>java org.apache.catalina.realm.RealmBase \
204    -a {algorithm} -e {encoding} {input}
205</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
206but care is required to ensure that the non-ASCII input is
207correctly passed to the digester.
208The digester returns <code>{input}:{digest}</code>. If the input appears
209corrupted in the return, the digest will be invalid.</p>
210
211</blockquote></td></tr></table>
212
213
214
215<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Example Application"><strong>Example Application</strong></a></font></td></tr><tr><td><blockquote>
216
217<p>The example application shipped with Tomcat 6 includes an area that is
218protected by a security constraint, utilizing form-based login.  To access it,
219point your browser at
220<a href="http://localhost:8080/examples/jsp/security/protected/">http://localhost:8080/examples/jsp/security/protected/</a>
221and log on with one of the usernames and passwords described for the default
222<a href="#MemoryRealm">MemoryRealm</a>.</p>
223
224</blockquote></td></tr></table>
225
226
227<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Manager Application"><strong>Manager Application</strong></a></font></td></tr><tr><td><blockquote>
228
229<p>If you wish to use the <a href="manager-howto.html">Manager Application</a>
230to deploy and undeploy applications in a running Tomcat 6 installation, you
231MUST add the "manager" role to at least one username in your selected Realm
232implementation.  This is because the manager web application itself uses a
233security constraint that requires role "manager" to access ANY request URI
234within that application.</p>
235
236<p>For security reasons, no username in the default Realm (i.e. using
237<code>conf/tomcat-users.xml</code> is assigned the "manager" role.  Therfore,
238no one will be able to utilize the features of this application until the
239Tomcat administrator specifically assigns this role to one or more users.</p>
240
241</blockquote></td></tr></table>
242
243<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Realm Logging"><strong>Realm Logging</strong></a></font></td></tr><tr><td><blockquote>
244
245<p>Debugging and exception messages logged by a <code>Realm</code> will
246   be recorded by the logging configuration associated with the container
247   for the realm: its surrounding <a href="../config/context.html">Context</a>,
248   <a href="../config/host.html">Host</a>, or
249   <a href="../config/engine.html">Engine</a>.</p>
250
251</blockquote></td></tr></table>
252
253</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Standard Realm Implementations"><strong>Standard Realm Implementations</strong></a></font></td></tr><tr><td><blockquote>
254
255<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="JDBCRealm"><strong>JDBCRealm</strong></a></font></td></tr><tr><td><blockquote>
256
257<h3>Introduction</h3>
258
259<p><strong>JDBCRealm</strong> is an implementation of the Tomcat 6
260<code>Realm</code> interface that looks up users in a relational database
261accessed via a JDBC driver.  There is substantial configuration flexibility
262that lets you adapt to existing table and column names, as long as your
263database structure conforms to the following requirements:</p>
264<ul>
265<li>There must be a table, referenced below as the <em>users</em> table,
266    that contains one row for every valid user that this <code>Realm</code>
267    should recognize.</li>
268<li>The <em>users</em> table must contain at least two columns (it may
269    contain more if your existing applications required it):
270    <ul>
271    <li>Username to be recognized by Tomcat when the user logs in.</li>
272    <li>Password to be recognized by Tomcat when the user logs in.
273        This value may in cleartext or digested - see below for more
274        information.</li>
275    </ul></li>
276<li>There must be a table, referenced below as the <em>user roles</em> table,
277    that contains one row for every valid role that is assigned to a
278    particular user.  It is legal for a user to have zero, one, or more than
279    one valid role.</li>
280<li>The <em>user roles</em> table must contain at least two columns (it may
281    contain more if your existing applications required it):
282    <ul>
283    <li>Username to be recognized by Tomcat (same value as is specified
284        in the <em>users</em> table).</li>
285    <li>Role name of a valid role associated with this user.</li>
286    </ul></li>
287</ul>
288
289<h3>Quick Start</h3>
290
291<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
292<ol>
293<li>If you have not yet done so, create tables and columns in your database
294    that conform to the requirements described above.</li>
295<li>Configure a database username and password for use by Tomcat, that has
296    at least read only access to the tables described above.  (Tomcat will
297    never attempt to write to these tables.)</li>
298<li>Place a copy of the JDBC driver you will be using inside the
299    <code>$CATALINA_HOME/lib</code> directory.
300    Note that <strong>only</strong> JAR files are recognized!</li>
301<li>Set up a <code>&lt;Realm&gt;</code> element, as described below, in your
302    <code>$CATALINA_BASE/conf/server.xml</code> file.</li>
303<li>Restart Tomcat 6 if it is already running.</li>
304</ol>
305
306<h3>Realm Element Attributes</h3>
307
308<p>To configure JDBCRealm, you will create a <code>&lt;Realm&gt;</code>
309element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
310as described <a href="#Configuring a Realm">above</a>.  The following
311attributes are supported by this implementation:</p>
312
313<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">
314    <p>The fully qualified Java class name of this Realm implementation.
315    You <strong>MUST</strong> specify the value
316    "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
317  </td></tr><tr><td valign="center" align="left"><strong><code>connectionName</code></strong></td><td valign="center" align="left">
318    <p>The database username used to establish a JDBC connection.</p>
319  </td></tr><tr><td valign="center" align="left"><strong><code>connectionPassword</code></strong></td><td valign="center" align="left">
320    <p>The database password used to establish a JDBC connection.</p>
321  </td></tr><tr><td valign="center" align="left"><strong><code>connectionURL</code></strong></td><td valign="center" align="left">
322    <p>The database URL used to establish a JDBC connection.</p>
323  </td></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left">
324    <p>The digest algorithm used to store passwords in non-plaintext formats.
325    Valid values are those accepted for the algorithm name by the
326    <code>java.security.MessageDigest</code> class.  See
327    <a href="#Digested Passwords">Digested Passwords</a> for more
328    information.  If not specified, passwords are stored in clear text.</p>
329  </td></tr><tr><td valign="center" align="left"><strong><code>driverName</code></strong></td><td valign="center" align="left">
330    <p>The fully qualified Java class name of the JDBC driver to be used.
331    Consult the documentation for your JDBC driver for the appropriate
332    value.</p>
333  </td></tr><tr><td valign="center" align="left"><strong><code>roleNameCol</code></strong></td><td valign="center" align="left">
334    <p>The name of the column, in the <em>user roles</em> table, that
335    contains the name of a role assigned to this user.</p>
336  </td></tr><tr><td valign="center" align="left"><strong><code>userCredCol</code></strong></td><td valign="center" align="left">
337    <p>The name of the column, in the <em>users</em> table, that contains
338    the password for this user (either in clear text, or digested if the
339    <code>digest</code> attribute is set).</p>
340  </td></tr><tr><td valign="center" align="left"><strong><code>userNameCol</code></strong></td><td valign="center" align="left">
341    <p>The name of the column, in the <em>users</em> and <em>user roles</em>
342    tables, that contains the username of this user.</p>
343  </td></tr><tr><td valign="center" align="left"><strong><code>userRoleTable</code></strong></td><td valign="center" align="left">
344    <p>The name of the table that contains one row for each <em>role</em>
345    assigned to a particular <em>username</em>.  This table must include at
346    least the columns named by the <code>userNameCol</code> and
347    <code>roleNameCol</code> attributes.</p>
348  </td></tr><tr><td valign="center" align="left"><strong><code>userTable</code></strong></td><td valign="center" align="left">
349    <p>The name of the table that contains one row for each <em>username</em>
350    to be recognized by Tomcat.  This table must include at least the columns
351    named by the <code>userNameCol</code> and <code>userCredCol</code>
352    attributes.</p>
353  </td></tr></table>
354
355<h3>Example</h3>
356
357<p>An example SQL script to create the needed tables might look something
358like this (adapt the syntax as required for your particular database):</p>
359<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
360create table users (
361  user_name         varchar(15) not null primary key,
362  user_pass         varchar(15) not null
363);
364
365create table user_roles (
366  user_name         varchar(15) not null,
367  role_name         varchar(15) not null,
368  primary key (user_name, role_name)
369);
370</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
371
372<p>Example <code>Realm</code> elements are included (commented out) in the
373default <code>$CATALINA_BASE/conf/server.xml</code> file.  Here's an example
374for using a MySQL database called "authority", configured with the tables
375described above, and accessed with username "dbuser" and password "dbpass":</p>
376<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
377&lt;Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"
378      driverName="org.gjt.mm.mysql.Driver"
379   connectionURL="jdbc:mysql://localhost/authority?user=dbuser&amp;amp;password=dbpass"
380       userTable="users" userNameCol="user_name" userCredCol="user_pass"
381   userRoleTable="user_roles" roleNameCol="role_name"/&gt;
382</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
383
384<h3>Additional Notes</h3>
385
386<p>JDBCRealm operates according to the following rules:</p>
387<ul>
388<li>When a user attempts to access a protected resource for the first time,
389    Tomcat 6 will call the <code>authenticate()</code> method of this
390    <code>Realm</code>.  Thus, any changes you have made to the database
391    directly (new users, changed passwords or roles, etc.) will be immediately
392    reflected.</li>
393<li>Once a user has been authenticated, the user (and his or her associated
394    roles) are cached within Tomcat for the duration of the user's login.
395    (For FORM-based authentication, that means until the session times out or
396    is invalidated; for BASIC authentication, that means until the user
397    closes their browser).  The cached user is <strong>not</strong> saved and
398    restored across sessions serialisations. Any changes to the database
399    information for an already authenticated user will <strong>not</strong> be
400    reflected until the next time that user logs on again.</li>
401<li>Administering the information in the <em>users</em> and <em>user roles</em>
402    table is the responsibility of your own applications.  Tomcat does not
403    provide any built-in capabilities to maintain users and roles.</li>
404</ul>
405
406</blockquote></td></tr></table>
407
408
409<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="DataSourceRealm"><strong>DataSourceRealm</strong></a></font></td></tr><tr><td><blockquote>
410
411<h3>Introduction</h3>
412
413<p><strong>DataSourceRealm</strong> is an implementation of the Tomcat 6
414<code>Realm</code> interface that looks up users in a relational database
415accessed via a JNDI named JDBC DataSource.  There is substantial configuration
416flexibility that lets you adapt to existing table and column names, as long
417as your database structure conforms to the following requirements:</p>
418<ul>
419<li>There must be a table, referenced below as the <em>users</em> table,
420    that contains one row for every valid user that this <code>Realm</code>
421    should recognize.</li>
422<li>The <em>users</em> table must contain at least two columns (it may
423    contain more if your existing applications required it):
424    <ul>
425    <li>Username to be recognized by Tomcat when the user logs in.</li>
426    <li>Password to be recognized by Tomcat when the user logs in.
427        This value may in cleartext or digested - see below for more
428        information.</li>
429    </ul></li>   
430<li>There must be a table, referenced below as the <em>user roles</em> table,
431    that contains one row for every valid role that is assigned to a
432    particular user.  It is legal for a user to have zero, one, or more than
433    one valid role.</li>
434<li>The <em>user roles</em> table must contain at least two columns (it may
435    contain more if your existing applications required it):
436    <ul>
437    <li>Username to be recognized by Tomcat (same value as is specified
438        in the <em>users</em> table).</li>
439    <li>Role name of a valid role associated with this user.</li>
440    </ul></li>
441</ul>
442
443<h3>Quick Start</h3>
444                 
445<p>To set up Tomcat to use DataSourceRealm, you will need to follow these steps:</p>
446<ol>             
447<li>If you have not yet done so, create tables and columns in your database
448    that conform to the requirements described above.</li>
449<li>Configure a database username and password for use by Tomcat, that has
450    at least read only access to the tables described above.  (Tomcat will
451    never attempt to write to these tables.)</li>
452<li>Configure a JNDI named JDBC DataSource for your database.  Refer to the
453    <a href="jndi-datasource-examples-howto.html">JNDI DataSource Example HOW-TO</a>
454    for information on how to configure a JNDI named JDBC DataSource.</li>
455<li>Set up a <code>&lt;Realm&gt;</code> element, as described below, in your
456    <code>$CATALINA_BASE/conf/server.xml</code> file.</li>
457<li>Restart Tomcat 6 if it is already running.</li>
458</ol>
459
460<h3>Realm Element Attributes</h3>
461
462<p>To configure DataSourceRealm, you will create a <code>&lt;Realm&gt;</code>
463element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
464as described <a href="#Configuring a Realm">above</a>.  The following
465attributes are supported by this implementation:</p>
466
467<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">
468    <p>The fully qualified Java class name of this Realm implementation.
469    You <strong>MUST</strong> specify the value
470    "<code>org.apache.catalina.realm.DataSourceRealm</code>" here.</p>
471  </td></tr><tr><td valign="center" align="left"><strong><code>dataSourceName</code></strong></td><td valign="center" align="left">
472    <p>The JNDI named JDBC DataSource for your database. If the DataSource is
473    local to the context, the name is relative to <code>java:/comp/env</code>,
474    and otherwise the name should match the name used to define the global
475    DataSource.</p>
476  </td></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left">
477    <p>The digest algorithm used to store passwords in non-plaintext formats.
478    Valid values are those accepted for the algorithm name by the
479    <code>java.security.MessageDigest</code> class.  See
480    <a href="#Digested Passwords">Digested Passwords</a> for more
481    information.  If not specified, passwords are stored in clear text.</p>
482  </td></tr><tr><td valign="center" align="left"><code>localDataSource</code></td><td valign="center" align="left">
483    <p>When the realm is nested inside a Context element, this allows the
484    realm to use a DataSource defined for the Context rather than a global
485    DataSource.  If not specified, the default is <code>false</code>: use a
486    global DataSource.</p>
487  </td></tr><tr><td valign="center" align="left"><strong><code>roleNameCol</code></strong></td><td valign="center" align="left">
488    <p>The name of the column, in the <em>user roles</em> table, that
489    contains the name of a role assigned to this user.</p>
490  </td></tr><tr><td valign="center" align="left"><strong><code>userCredCol</code></strong></td><td valign="center" align="left">
491    <p>The name of the column, in the <em>users</em> table, that contains
492    the password for this user (either in clear text, or digested if the
493    <code>digest</code> attribute is set).</p>
494  </td></tr><tr><td valign="center" align="left"><strong><code>userNameCol</code></strong></td><td valign="center" align="left">
495    <p>The name of the column, in the <em>users</em> and <em>user roles</em>
496    tables, that contains the username of this user.</p>
497  </td></tr><tr><td valign="center" align="left"><strong><code>userRoleTable</code></strong></td><td valign="center" align="left">
498    <p>The name of the table that contains one row for each <em>role</em>
499    assigned to a particular <em>username</em>.  This table must include at
500    least the columns named by the <code>userNameCol</code> and
501    <code>roleNameCol</code> attributes.</p>
502  </td></tr><tr><td valign="center" align="left"><strong><code>userTable</code></strong></td><td valign="center" align="left">
503    <p>The name of the table that contains one row for each <em>username</em>
504    to be recognized by Tomcat.  This table must include at least the columns
505    named by the <code>userNameCol</code> and <code>userCredCol</code>
506    attributes.</p>
507  </td></tr></table>
508
509<h3>Example</h3>
510
511<p>An example SQL script to create the needed tables might look something
512like this (adapt the syntax as required for your particular database):</p>
513<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
514create table users (
515  user_name         varchar(15) not null primary key,
516  user_pass         varchar(15) not null
517);
518
519create table user_roles (
520  user_name         varchar(15) not null,
521  role_name         varchar(15) not null,
522  primary key (user_name, role_name)
523);
524</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
525
526<p>Here is an example for using a MySQL database called "authority", configured
527with the tables described above, and accessed with the JNDI JDBC DataSource with
528name "java:/comp/env/jdbc/authority".</p>
529<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
530&lt;Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99"
531   dataSourceName="jdbc/authority"
532   userTable="users" userNameCol="user_name" userCredCol="user_pass"
533   userRoleTable="user_roles" roleNameCol="role_name"/&gt;
534</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
535
536<h3>Additional Notes</h3>
537
538<p>DataSourceRealm operates according to the following rules:</p>
539<ul>
540<li>When a user attempts to access a protected resource for the first time,
541    Tomcat 6 will call the <code>authenticate()</code> method of this
542    <code>Realm</code>.  Thus, any changes you have made to the database
543    directly (new users, changed passwords or roles, etc.) will be immediately
544    reflected.</li>
545<li>Once a user has been authenticated, the user (and his or her associated
546    roles) are cached within Tomcat for the duration of the user's login.
547    (For FORM-based authentication, that means until the session times out or
548    is invalidated; for BASIC authentication, that means until the user
549    closes their browser).  The cached user is <strong>not</strong> saved and
550    restored across sessions serialisations. Any changes to the database
551    information for an already authenticated user will <strong>not</strong> be
552    reflected until the next time that user logs on again.</li>
553<li>Administering the information in the <em>users</em> and <em>user roles</em>
554    table is the responsibility of your own applications.  Tomcat does not
555    provide any built-in capabilities to maintain users and roles.</li>
556</ul>
557
558</blockquote></td></tr></table>
559
560
561<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="JNDIRealm"><strong>JNDIRealm</strong></a></font></td></tr><tr><td><blockquote>
562
563<h3>Introduction</h3>
564
565<p><strong>JNDIRealm</strong> is an implementation of the Tomcat 6
566<code>Realm</code> interface that looks up users in an LDAP directory
567server accessed by a JNDI provider (typically, the standard LDAP
568provider that is available with the JNDI API classes). The realm
569supports a variety of approaches to using a directory for
570authentication.</p>
571
572<h4>Connecting to the directory</h4>
573
574<p>The realm's connection to the directory is defined by the
575<strong>connectionURL</strong> configuration attribute. This is a URL
576whose format is defined by the JNDI provider. It is usually an LDAP
577URL that specifies the domain name of the directory server to connect
578to, and optionally the port number and distinguished name (DN) of the
579required root naming context.</p>
580
581<p>If you have more than one provider you can configure an
582<strong>alternateURL</strong>.  If a socket connection can not be
583made to the provider at the <strong>connectionURL</strong> an
584attempt will be made to use the <strong>alternateURL</strong>.</p>
585
586<p>When making a connection in order to search the directory and
587retrieve user and role information, the realm authenticates itself to
588the directory with the username and password specified by the
589<strong>connectionName</strong> and
590<strong>connectionPassword</strong> properties. If these properties
591are not specified the connection is anonymous. This is sufficient in
592many cases.
593</p>
594
595
596<h4>Selecting the user's directory entry</h4>
597
598<p>Each user that can be authenticated must be represented in the
599directory by an individual entry that corresponds to an element in the
600initial <code>DirContext</code> defined by the
601<strong>connectionURL</strong> attribute. This user entry must have an
602attribute containing the username that is presented for
603authentication.</p>
604
605<p>Often the distinguished name of the user's entry contains the
606username presented for authentication but is otherwise the same for
607all users. In this case the <strong>userPattern</strong> attribute may
608be used to specify the DN, with "{0}" marking where
609the username should be substituted.</p>
610
611<p>Otherwise the realm must search the directory to find a unique entry
612containing the username. The following attributes configure this
613search:
614
615     <ul>
616     <li><strong>userBase</strong> - the entry that is the base of
617         the subtree containing users.  If not specified, the search
618         base is the top-level context.</li>
619
620     <li><strong>userSubtree</strong> - the search scope. Set to
621         <code>true</code> if you wish to search the entire subtree
622         rooted at the <strong>userBase</strong> entry. The default value
623         of <code>false</code> requests a single-level search
624         including only the top level.</li>
625
626     <li><strong>userSearch</strong> - pattern specifying the LDAP
627         search filter to use after substitution of the username.</li>
628
629    </ul>
630</p>
631
632
633<h4>Authenticating the user</h4>
634
635<ul>
636<li>
637<p><b>Bind mode</b></p>
638
639<p>By default the realm authenticates a user by binding to
640the directory with the DN of the entry for that user and the password
641presented by the user. If this simple bind succeeds the user is considered to
642be authenticated.</p>
643
644<p>For security reasons a directory may store a digest of the user's
645password rather than the clear text version (see <a href="#Digested Passwords">Digested Passwords</a> for more information). In that case,
646as part of the simple bind operation the directory automatically
647computes the correct digest of the plaintext password presented by the
648user before validating it against the stored value. In bind mode,
649therefore, the realm is not involved in digest processing. The
650<strong>digest</strong> attribute is not used, and will be ignored if
651set.</p>
652</li>
653
654<li>
655<p><b>Comparison mode</b></p>
656<p>Alternatively, the realm may retrieve the stored
657password from the directory and compare it explicitly with the value
658presented by the user. This mode is configured by setting the
659<strong>userPassword</strong> attribute to the name of a directory
660attribute in the user's entry that contains the password.</p>
661
662<p>Comparison mode has some disadvantages. First, the
663<strong>connectionName</strong> and
664<strong>connectionPassword</strong> attributes must be configured to
665allow the realm to read users' passwords in the directory. For
666security reasons this is generally undesirable; indeed many directory
667implementations will not allow even the directory manager to read
668these passwords. In addition, the realm must handle password digests
669itself, including variations in the algorithms used and ways of
670representing password hashes in the directory. However, the realm may
671sometimes need access to the stored password, for example to support
672HTTP Digest Access Authentication (RFC 2069). (Note that HTTP digest
673authentication is different from the storage of password digests in
674the repository for user information as discussed above).
675</p>
676</li>
677</ul>
678
679<h4>Assigning roles to the user</h4>
680
681<p>The directory realm supports two approaches to the representation
682of roles in the directory:</p>
683
684<ul>
685<li>
686<p><b>Roles as explicit directory entries</b></p>
687
688<p>Roles may be represented by explicit directory entries. A role
689entry is usually an LDAP group entry with one attribute
690containing the name of the role and another whose values are the
691distinguished names or usernames of the users in that role.  The
692following attributes configure a directory search to
693find the names of roles associated with the authenticated user:</p>
694
695<ul>
696<li><strong>roleBase</strong> - the base entry for the role search.
697    If not specified, the search base is the top-level directory
698    context.</li>
699
700<li><strong>roleSubtree</strong> - the search
701    scope. Set to <code>true</code> if you wish to search the entire
702    subtree rooted at the <code>roleBase</code> entry. The default
703    value of <code>false</code> requests a single-level search
704    including the top level only.</li>
705
706<li><strong>roleSearch</strong> - the LDAP search filter for
707    selecting role entries. It optionally includes pattern
708    replacements "{0}" for the distinguished name and/or "{1}" for the
709    username of the authenticated user.</li>
710
711<li><strong>roleName</strong> - the attribute in a role entry
712     containing the name of that role.</li>
713
714</ul>
715
716</li>
717</ul>
718
719<ul>
720<li>
721<p><b>Roles as an attribute of the user entry</b></p>
722
723<p>Role names may also be held as the values of an attribute in the
724user's directory entry. Use <strong>userRoleName</strong> to specify
725the name of this attribute.</p>
726
727</li>
728</ul>
729<p>A combination of both approaches to role representation may be used.</p>
730
731<h3>Quick Start</h3>
732
733<p>To set up Tomcat to use JNDIRealm, you will need to follow these steps:</p>
734<ol>
735<li>Make sure your directory server is configured with a schema that matches
736    the requirements listed above.</li>
737<li>If required, configure a username and password for use by Tomcat, that has
738    read only access to the information described above.  (Tomcat will
739    never attempt to modify this information.)</li>
740<li>Place a copy of the JNDI driver you will be using (typically
741    <code>ldap.jar</code> available with JNDI) inside the
742    <code>$CATALINA_HOME/lib</code> directory.</li>
743<li>Set up a <code>&lt;Realm&gt;</code> element, as described below, in your
744    <code>$CATALINA_BASE/conf/server.xml</code> file.</li>
745<li>Restart Tomcat 6 if it is already running.</li>
746</ol>
747
748<h3>Realm Element Attributes</h3>
749
750<p>To configure JNDIRealm, you will create a <code>&lt;Realm&gt;</code>
751element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
752as described <a href="#Configuring a Realm">above</a>.  The following
753attributes are supported by this implementation:</p>
754
755<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">
756    <p>The fully qualified Java class name of this Realm implementation.
757    You <strong>MUST</strong> specify the value
758    "<code>org.apache.catalina.realm.JNDIRealm</code>" here.</p>
759  </td></tr><tr><td valign="center" align="left"><code>alternateURL</code></td><td valign="center" align="left">
760        <p>If a socket connection can not be made to the provider at
761        the <code>connectionURL</code> an attempt will be made to use the
762        <code>alternateURL</code>.</p>
763      </td></tr><tr><td valign="center" align="left"><code>authentication</code></td><td valign="center" align="left">
764        <p>A string specifying the type of authentication to use.
765        "none", "simple", "strong" or a provider specific definition
766        can be used. If no value is given the providers default is used.</p>
767      </td></tr><tr><td valign="center" align="left"><code>connectionName</code></td><td valign="center" align="left">
768        <p>The directory username to use when establishing a
769        connection to the directory for LDAP search operations. If not
770        specified an anonymous connection is made, which is often
771        sufficient unless you specify the <code>userPassword</code>
772        property.</p>
773      </td></tr><tr><td valign="center" align="left"><code>connectionPassword</code></td><td valign="center" align="left">
774        <p>The directory password to use when establishing a
775        connection to the directory for LDAP search operations. If not
776        specified an anonymous connection is made, which is often
777        sufficient unless you specify the <code>userPassword</code>
778        property.</p>
779      </td></tr><tr><td valign="center" align="left"><strong><code>connectionURL</code></strong></td><td valign="center" align="left">
780        <p>The connection URL to be passed to the JNDI driver when
781        establishing a connection to the directory.</p>
782      </td></tr><tr><td valign="center" align="left"><code>contextFactory</code></td><td valign="center" align="left">
783        <p>The fully qualified Java class name of the JNDI context
784        factory to be used for this connection.  By default, the standard
785        JNDI LDAP provider is used
786        (<code>com.sun.jndi.ldap.LdapCtxFactory</code>).</p>
787      </td></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left">
788        <p>The digest algorithm to apply to the plaintext password offered
789        by the user before comparing it with the value retrieved from the
790        directory.  Valid values are those accepted for the algorithm name
791        by the <code>java.security.MessageDigest</code> class.  See <a href="#Digested Passwords">Digested Passwords</a> for more
792        information. If not specified the plaintext password is assumed to
793        be retrieved. Not required unless <code>userPassword</code> is
794        specified</p>
795      </td></tr><tr><td valign="center" align="left"><code>protocol</code></td><td valign="center" align="left">
796         <p>A string specifying the security protocol to use. If not given
797         the providers default is used.</p>
798      </td></tr><tr><td valign="center" align="left"><code>roleBase</code></td><td valign="center" align="left">
799        <p>The base directory entry for performing role searches. If
800        not specified, the top level element in the directory context
801        will be used.</p>
802      </td></tr><tr><td valign="center" align="left"><code>roleName</code></td><td valign="center" align="left">
803        <p>The name of the attribute that contains role names in the
804        directory entries found by a role search. In addition you can
805        use the <code>userRoleName</code> property to specify the name
806        of an attribute, in the user's entry, containing additional
807        role names.  If <code>roleName</code> is not specified a role
808        search does not take place, and roles are taken only from the
809        user's entry.</p>
810      </td></tr><tr><td valign="center" align="left"><code>roleSearch</code></td><td valign="center" align="left">
811        <p>The LDAP filter expression used for performing role
812        searches, following the syntax supported by the
813        <code>java.text.MessageFormat</code> class.  Use
814        <code>{0}</code> to substitute the distinguished name (DN) of
815        the user, and/or <code>{1}</code> to substitute the
816        username. If not specified a role search does not take place
817        and roles are taken only from the attribute in the user's
818        entry specified by the <code>userRoleName</code> property.</p>
819      </td></tr><tr><td valign="center" align="left"><code>roleSubtree</code></td><td valign="center" align="left">
820        <p>Set to <code>true</code> if you want to search the entire
821        subtree of the element specified by the <code>roleBase</code>
822        property for role entries associated with the user. The
823        default value of <code>false</code> causes only the top level
824        to be searched.</p>
825      </td></tr><tr><td valign="center" align="left"><code>userBase</code></td><td valign="center" align="left">
826        <p>The base element for user searches performed using the
827        <code>userSearch</code> expression.  If not specified, the top
828        level element in the directory context will be used. Not used
829        if you are using the <code>userPattern</code> expression.</p>
830      </td></tr><tr><td valign="center" align="left"><code>userPassword</code></td><td valign="center" align="left">
831        <p>Name of the attribute in the user's entry containing the
832        user's password.  If you specify this value, JNDIRealm will
833        bind to the directory using the values specified by
834        <code>connectionName</code> and
835        <code>connectionPassword</code> properties, and retrieve the
836        corresponding attribute for comparison to the value specified
837        by the user being authenticated.  If the <code>digest</code>
838        attribute is set, the specified digest algorithm is applied to
839        the password offered by the user before comparing it with the
840        value retrieved from the directory.  If you do
841        <strong>not</strong> specify this value, JNDIRealm will
842        attempt a simple bind to the directory using the DN of the
843        user's entry and password specified by the user, with a
844        successful bind being interpreted as an authenticated
845        user.</p>
846      </td></tr><tr><td valign="center" align="left"><code>userPattern</code></td><td valign="center" align="left">
847        <p>A pattern for the distinguished name (DN) of the user's
848        directory entry, following the syntax supported by the
849        <code>java.text.MessageFormat</code> class with
850        <code>{0}</code> marking where the actual username should be
851        inserted. You can use this property instead of
852        <code>userSearch</code>, <code>userSubtree</code> and
853        <code>userBase</code> when the distinguished name contains the
854        username and is otherwise the same for all users.</p>
855      </td></tr><tr><td valign="center" align="left"><code>userRoleName</code></td><td valign="center" align="left">
856        <p>The name of an attribute in the user's directory entry
857        containing zero or more values for the names of roles assigned
858        to this user.  In addition you can use the
859        <code>roleName</code> property to specify the name of an
860        attribute to be retrieved from individual role entries found
861        by searching the directory. If <code>userRoleName</code> is
862        not specified all the roles for a user derive from the role
863        search.</p>
864      </td></tr><tr><td valign="center" align="left"><code>userSearch</code></td><td valign="center" align="left">
865        <p>The LDAP filter expression to use when searching for a
866        user's directory entry, with <code>{0}</code> marking where
867        the actual username should be inserted.  Use this property
868        (along with the <code>userBase</code> and
869        <code>userSubtree</code> properties) instead of
870        <code>userPattern</code> to search the directory for the
871        user's entry.</p>
872      </td></tr><tr><td valign="center" align="left"><code>userSubtree</code></td><td valign="center" align="left">
873        <p>Set to <code>true</code> if you want to search the entire
874        subtree of the element specified by the <code>userBase</code>
875        property for the user's entry. The default value of
876        <code>false</code> causes only the top level to be searched.
877        Not used if you are using the <code>userPattern</code>
878        expression.</p>
879      </td></tr></table>
880
881<h3>Example</h3>
882
883<p>Creation of the appropriate schema in your directory server is beyond the
884scope of this document, because it is unique to each directory server
885implementation.  In the examples below, we will assume that you are using a
886distribution of the OpenLDAP directory server (version 2.0.11 or later), which
887can be downloaded from
888<a href="http://www.openldap.org">http://www.openldap.org</a>.  Assume that
889your <code>slapd.conf</code> file contains the following settings
890(among others):</p>
891<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
892database ldbm
893suffix dc="mycompany",dc="com"
894rootdn "cn=Manager,dc=mycompany,dc=com"
895rootpw secret
896</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
897
898<p>We will assume for <code>connectionURL</code> that the directory
899server runs on the same machine as Tomcat.  See <a href="http://java.sun.com/products/jndi/docs.html">http://java.sun.com/products/jndi/docs.html</a>
900for more information about configuring and using the JNDI LDAP
901provider.</p>
902
903<p>Next, assume that this directory server has been populated with elements
904as shown below (in LDIF format):</p>
905
906<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
907
908# Define top-level entry
909dn: dc=mycompany,dc=com
910objectClass: dcObject
911dc:mycompany
912
913# Define an entry to contain people
914# searches for users are based on this entry
915dn: ou=people,dc=mycompany,dc=com
916objectClass: organizationalUnit
917ou: people
918
919# Define a user entry for Janet Jones
920dn: uid=jjones,ou=people,dc=mycompany,dc=com
921objectClass: inetOrgPerson
922uid: jjones
923sn: jones
924cn: janet jones
925mail: j.jones@mycompany.com
926userPassword: janet
927
928# Define a user entry for Fred Bloggs
929dn: uid=fbloggs,ou=people,dc=mycompany,dc=com
930objectClass: inetOrgPerson
931uid: fbloggs
932sn: bloggs
933cn: fred bloggs
934mail: f.bloggs@mycompany.com
935userPassword: fred
936
937# Define an entry to contain LDAP groups
938# searches for roles are based on this entry
939dn: ou=groups,dc=mycompany,dc=com
940objectClass: organizationalUnit
941ou: groups
942
943# Define an entry for the "tomcat" role
944dn: cn=tomcat,ou=groups,dc=mycompany,dc=com
945objectClass: groupOfUniqueNames
946cn: tomcat
947uniqueMember: uid=jjones,ou=people,dc=mycompany,dc=com
948uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com
949
950# Define an entry for the "role1" role
951dn: cn=role1,ou=groups,dc=mycompany,dc=com
952objectClass: groupOfUniqueNames
953cn: role1
954uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com
955</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
956
957<p>An example <code>Realm</code> element for the OpenLDAP directory
958server configured as described above might look like this, assuming
959that users use their uid (e.g. jjones) to login to the
960application and that an anonymous connection is sufficient to search
961the directory and retrieve role information:</p>
962
963<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
964&lt;Realm   className="org.apache.catalina.realm.JNDIRealm" debug="99"
965     connectionURL="ldap://localhost:389"
966       userPattern="uid={0},ou=people,dc=mycompany,dc=com"
967          roleBase="ou=groups,dc=mycompany,dc=com"
968          roleName="cn"
969        roleSearch="(uniqueMember={0})"
970/&gt;
971</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
972
973<p>With this configuration, the realm will determine the user's
974distinguished name by substituting the username into the
975<code>userPattern</code>, authenticate by binding to the directory
976with this DN and the password received from the user, and search the
977directory to find the user's roles.</p>
978
979<p>Now suppose that users are expected to enter their email address
980rather than their userid when logging in. In this case the realm must
981search the directory for the user's entry. (A search is also necessary
982when user entries are held in multiple subtrees corresponding perhaps
983to different organizational units or company locations).</p>
984
985<p>Further, suppose that in addition to the group entries you want to
986use an attribute of the user's entry to hold roles. Now the entry for
987Janet Jones might read as follows:</p>
988
989<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
990dn: uid=jjones,ou=people,dc=mycompany,dc=com
991objectClass: inetOrgPerson
992uid: jjones
993sn: jones
994cn: janet jones
995mail: j.jones@mycompany.com
996memberOf: role2
997memberOf: role3
998userPassword: janet
999</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
1000
1001<p> This realm configuration would satisfy the new requirements:</p>
1002
1003<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
1004&lt;Realm   className="org.apache.catalina.realm.JNDIRealm" debug="99"
1005     connectionURL="ldap://localhost:389"
1006          userBase="ou=people,dc=mycompany,dc=com"
1007        userSearch="(mail={0})"
1008      userRoleName="memberOf"
1009          roleBase="ou=groups,dc=mycompany,dc=com"
1010          roleName="cn"
1011        roleSearch="(uniqueMember={0})"
1012/&gt;
1013</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
1014
1015<p>Now when Janet Jones logs in as "j.jones@mycompany.com", the realm
1016searches the directory for a unique entry with that value as its mail
1017attribute and attempts to bind to the directory as
1018<code>uid=jjones,ou=people,dc=mycompany,dc=com</code> with the given
1019password. If authentication succeeds, she is assigned three roles:
1020"role2" and "role3", the values of the "memberOf" attribute in her
1021directory entry, and "tomcat", the value of the "cn" attribute in the
1022only group entry of which she is a member.</p>
1023
1024<p>Finally, to authenticate the user by retrieving
1025the password from the directory and making a local comparison in the
1026realm, you might use a realm configuration like this:</p>
1027
1028<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
1029&lt;Realm   className="org.apache.catalina.realm.JNDIRealm" debug="99"
1030    connectionName="cn=Manager,dc=mycompany,dc=com"
1031connectionPassword="secret"
1032     connectionURL="ldap://localhost:389"
1033      userPassword="userPassword"
1034       userPattern="uid={0},ou=people,dc=mycompany,dc=com"
1035          roleBase="ou=groups,dc=mycompany,dc=com"
1036          roleName="cn"
1037        roleSearch="(uniqueMember={0})"
1038/&gt;
1039</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
1040
1041<p>However, as discussed above, the default bind mode for
1042authentication is usually to be preferred.</p>
1043
1044<h3>Additional Notes</h3>
1045
1046<p>JNDIRealm operates according to the following rules:</p>
1047<ul>
1048<li>When a user attempts to access a protected resource for the first time,
1049    Tomcat 6 will call the <code>authenticate()</code> method of this
1050    <code>Realm</code>.  Thus, any changes you have made to the directory
1051    (new users, changed passwords or roles, etc.) will be immediately
1052    reflected.</li>
1053<li>Once a user has been authenticated, the user (and his or her associated
1054    roles) are cached within Tomcat for the duration of the user's login.
1055    (For FORM-based authentication, that means until the session times out or
1056    is invalidated; for BASIC authentication, that means until the user
1057    closes their browser).  The cached user is <strong>not</strong> saved and
1058    restored across sessions serialisations. Any changes to the directory
1059    information for an already authenticated user will <strong>not</strong> be
1060    reflected until the next time that user logs on again.</li>
1061<li>Administering the information in the directory server
1062    is the responsibility of your own applications.  Tomcat does not
1063    provide any built-in capabilities to maintain users and roles.</li>
1064</ul>
1065
1066</blockquote></td></tr></table>
1067
1068
1069<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="MemoryRealm"><strong>MemoryRealm</strong></a></font></td></tr><tr><td><blockquote>
1070
1071<h3>Introduction</h3>
1072
1073<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
1074Tomcat 6 <code>Realm</code> interface.  It is not designed for production use.
1075At startup time, MemoryRealm loads information about all users, and their
1076corresponding roles, from an XML document (by default, this document is loaded from <code>$CATALINA_BASE/conf/tomcat-users.xml</code>).  Changes to the data
1077in this file are not recognized until Tomcat is restarted.</p>
1078
1079<h3>Realm Element Attributes</h3>
1080
1081<p>To configure MemoryRealm, you will create a <code>&lt;Realm&gt;</code>
1082element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
1083as described <a href="#Configuring a Realm">above</a>.  The following
1084attributes are supported by this implementation:</p>
1085
1086<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">
1087    <p>The fully qualified Java class name of this Realm implementation.
1088    You <strong>MUST</strong> specify the value
1089    "<code>org.apache.catalina.realm.MemoryRealm</code>" here.</p>
1090  </td></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left">
1091    <p>The digest algorithm used to store passwords in non-plaintext formats.
1092    Valid values are those accepted for the algorithm name by the
1093    <code>java.security.MessageDigest</code> class.  See
1094    <a href="#Digested Passwords">Digested Passwords</a> for more
1095    information.  If not specified, passwords are stored in clear text.</p>
1096  </td></tr><tr><td valign="center" align="left"><code>pathname</code></td><td valign="center" align="left">
1097    <p>Absolute or relative (to $CATALINA_BASE) pathname of the XML document
1098    containing our valid usernames, passwords, and roles.  See below for more
1099    information on the format of this file.  If not specified, the value
1100    <code>conf/tomcat-users.xml</code> is used.</p>
1101  </td></tr></table>
1102
1103<h3>User File Format</h3>
1104
1105<p>The users file (by default, <code>conf/tomcat-users.xml</code> must be an
1106XML document, with a root element <code>&lt;tomcat-users&gt;</code>.  Nested
1107inside the root element will be a <code>&lt;user&gt;</code> element for each
1108valid user, consisting of the following attributes:</p>
1109<ul>
1110<li><strong>name</strong> - Username this user must log on with.</li>
1111<li><strong>password</strong> - Password this user must log on with (in
1112    clear text if the <code>digest</code> attribute was not set on the
1113    <code>&lt;Realm&gt;</code> element, or digested appropriately as
1114    described <a href="#Digested Passwords">here</a> otherwise).</li>
1115<li><strong>roles</strong> - Comma-delimited list of the role names
1116    associated with this user.</li>
1117</ul>
1118
1119<h3>Example</h3>
1120
1121<p>The default installation of Tomcat 6 is configured with a MemoryRealm
1122nested inside the <code>&lt;Engine&gt;</code> element, so that it applies
1123to all virtual hosts and web applications.  The default contents of the
1124<code>conf/tomcat-users.xml</code> file is:</p>
1125<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
1126&lt;tomcat-users&gt;
1127  &lt;user name="tomcat" password="tomcat" roles="tomcat" /&gt;
1128  &lt;user name="role1"  password="tomcat" roles="role1"  /&gt;
1129  &lt;user name="both"   password="tomcat" roles="tomcat,role1" /&gt;
1130&lt;/tomcat-users&gt;
1131</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
1132
1133<h3>Additional Notes</h3>
1134
1135<p>MemoryRealm operates according to the following rules:</p>
1136<ul>
1137<li>When Tomcat first starts up, it loads all defined users and their
1138    associated information from the users file.  Changes to the data in
1139    this file will <strong>not</strong> be recognized until Tomcat is
1140    restarted.</li>
1141<li>When a user attempts to access a protected resource for the first time,
1142    Tomcat 6 will call the <code>authenticate()</code> method of this
1143    <code>Realm</code>.</li>
1144<li>Once a user has been authenticated, the user (and his or her associated
1145    roles) are cached within Tomcat for the duration of the user's login.
1146    (For FORM-based authentication, that means until the session times out or
1147    is invalidated; for BASIC authentication, that means until the user
1148    closes their browser).  The cached user is <strong>not</strong> saved and
1149    restored across sessions serialisations.</li>
1150<li>Administering the information in the users file is the responsibility
1151    of your application.  Tomcat does not
1152    provide any built-in capabilities to maintain users and roles.</li>
1153</ul>
1154
1155
1156</blockquote></td></tr></table>
1157
1158
1159<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="JAASRealm"><strong>JAASRealm</strong></a></font></td></tr><tr><td><blockquote>
1160
1161<h3>Introduction</h3>
1162
1163        <p><strong>JAASRealm</strong> is an implementation of the Tomcat
11646 <code>Realm</code> interface that authenticates users through the Java
1165Authentication &amp; Authorization Service (JAAS) framework which is now
1166provided as part of the standard J2SE API.</p>
1167        <p>Using JAASRealm gives the developer the ability to combine
1168practically any conceivable security realm with Tomcat's CMA. </p>
1169        <p>JAASRealm is prototype for Tomcat of the JAAS-based
1170J2EE authentication framework for J2EE v1.4, based on the <a href="http://www.jcp.org/en/jsr/detail?id=196">JCP Specification
1171Request 196</a> to enhance container-managed security and promote
1172'pluggable' authentication mechanisms whose implementations would be
1173container-independent.
1174        </p>
1175        <p>Based on the JAAS login module and principal (see <code>javax.security.auth.spi.LoginModule</code>
1176and <code>javax.security.Principal</code>), you can develop your own
1177security mechanism or wrap another third-party mechanism for
1178integration with the CMA as implemented by Tomcat.
1179        </p>
1180
1181        <h3>Quick Start</h3>
1182        <p>To set up Tomcat to use JAASRealm with your own JAAS login module,
1183 you will need to follow these steps:</p>
1184        <ol>
1185          <li>Write your own LoginModule, User and Role classes based
1186on JAAS (see
1187<a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/GeneralAcnOnly.html">the
1188JAAS Authentication Tutorial</a> and
1189<a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/JAASLMDevGuide.html">the JAAS Login Module
1190Developer's Guide</a>) to be managed by the JAAS Login
1191Context (<code>javax.security.auth.login.LoginContext</code>)
1192When developing your LoginModule, note that JAASRealm's built-in <code>CallbackHandler</code>
1193+only recognizes the <code>NameCallback</code> and <code>PasswordCallback</code> at present.
1194          </li>
1195          <li>Although not specified in JAAS, you should create
1196seperate classes to distinguish between users and roles, extending <code>javax.security.Principal</code>,
1197so that Tomcat can tell which Principals returned from your login
1198module are users and which are roles (see <code>org.apache.catalina.realm.JAASRealm</code>).
1199Regardless, the first Principal returned is <em>always</em> treated as the user Principal.
1200          </li>
1201          <li>Place the compiled classes on Tomcat's classpath
1202          </li>
1203          <li>Set up a login.config file for Java (see <a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS
1204LoginConfig file</a>) and tell Tomcat where to find it by specifying
1205its location to the JVM, for instance by setting the environment
1206variable: <code>JAVA_OPTS=-DJAVA_OPTS=-Djava.security.auth.login.config==$CATALINA_BASE/conf/jaas.config</code></li>
1207
1208          <li>Configure your security-constraints in your web.xml for
1209the resources you want to protect</li>
1210          <li>Configure the JAASRealm module in your server.xml </li>
1211          <li>Restart Tomcat 6 if it is already running.</li>
1212        </ol>
1213        <h3>Realm Element Attributes</h3>
1214        <p>To configure JAASRealm as for step 6 above, you create
1215a <code>&lt;Realm&gt;</code> element and nest it in your
1216<code>$CATALINA_BASE/conf/server.xml</code>
1217file within your <code>&lt;Engine&gt;</code> node. The following attributes
1218are supported by this implementation:</p>
1219
1220<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">
1221    <p>The fully qualified Java class name of this Realm implementation.
1222    You <strong>MUST</strong> specify the value
1223    "<code>org.apache.catalina.realm.JAASRealm</code>" here.</p>
1224  </td></tr><tr><td valign="center" align="left"><strong><code>appName</code></strong></td><td valign="center" align="left">
1225    <p>The name of the application as configured in your login configuration file
1226    (<a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS LoginConfig</a>).</p>
1227  </td></tr><tr><td valign="center" align="left"><strong><code>userClassNames</code></strong></td><td valign="center" align="left">
1228    <p>A comma-seperated list of the names of the classes that you have made
1229    for your user <code>Principals</code>.</p>
1230  </td></tr><tr><td valign="center" align="left"><code>roleClassNames</code></td><td valign="center" align="left">
1231    <p>A comma-seperated list of the names of the classes that you have made
1232    for your role <code>Principals</code>.</p>
1233  </td></tr><tr><td valign="center" align="left"><code>useContextClassLoader</code></td><td valign="center" align="left">
1234    <p>Instructs JAASRealm to use the context class loader for loading the user-specified
1235    <code>LoginModule</code> class and associated <code>Principal</code> classes. The
1236    default value is <code>true</code>, which is backwards-compatible with the way
1237    Tomcat 4 works. To load classes using the container's classloader, specify
1238    <code>false</code>.</p>
1239  </td></tr></table>
1240
1241<h3>Example</h3>
1242
1243<p>Here is an example of how your server.xml snippet should look.</p>
1244
1245<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
1246&lt;Realm className="org.apache.catalina.realm.JAASRealm"                 
1247                appName="MyFooRealm"       
1248    userClassNames="org.foobar.realm.FooUser"       
1249     roleClassNames="org.foobar.realm.FooRole"
1250                      debug="99"/&gt;
1251</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
1252
1253<p>It is the responsibility of your login module to create and save User and
1254Role objects representing Principals for the user
1255(<code>javax.security.auth.Subject</code>). If your login module doesn't
1256create a user object but also doesn't throw a login exception, then the
1257Tomcat CMA will break and you will be left at the
1258http://localhost:8080/myapp/j_security_check URI or at some other
1259unspecified location.</p>
1260
1261        <p>The flexibility of the JAAS approach is two-fold: </p>
1262        <ul>
1263          <li>you can carry out whatever processing you require behind
1264the scenes in your own login module.</li>
1265          <li>you can plug in a completely different LoginModule by changing the configuration
1266and restarting the server, without any code changes to your application.</li>
1267        </ul>
1268
1269        <h3>Additional Notes</h3>
1270        <ul>
1271          <li>When a user attempts to access a protected resource for
1272              the first time, Tomcat 6 will call the <code>authenticate()</code>
1273              method of this <code>Realm</code>.  Thus, any changes you have made in
1274              the security mechanism directly (new users, changed passwords or
1275              roles, etc.) will be immediately reflected.</li>
1276          <li>Once a user has been authenticated, the user (and his or
1277              her associated roles) are cached within Tomcat for the duration of
1278              the user's login.  For FORM-based authentication, that means until
1279              the session times out or is invalidated; for BASIC authentication,
1280              that means until the user closes their browser.  Any changes to the
1281              security information for an already authenticated user will <strong>not</strong>
1282              be reflected until the next time that user logs on again.</li>
1283          <li>As with other <code>Realm</code> implementations, digested passwords
1284              are supported if the <code>&lt;Realm&gt;</code> element in <code>server.xml</code>
1285              contains a <code>digest</code> attribute; JAASRealm's <code>CallbackHandler</code>
1286              will digest the password prior to passing it back to the <code>LoginModule</code></li> 
1287        </ul>
1288
1289</blockquote></td></tr></table>
1290
1291
1292</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>
1293        Copyright &copy; 1999-2008, Apache Software Foundation
1294        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.