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

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

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