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