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