Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / 6266f996613ae5631b7288523f895b36e30fe5af / . / tomcat-cas / webapps / docs / config / realm.html
blob: 95c091265918f82985d1a3dd5e5d5ebf93bf03f0 [file] [log] [blame]
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 Configuration Reference (7.0.77) - The Realm Component</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4</style><style type="text/css">
5code {background-color:rgb(224,255,255);padding:0 0.1em;}
6code.attributeName, code.propertyName {background-color:transparent;}
7
8
9table {
10 border-collapse: collapse;
11 text-align: left;
12}
13table *:not(table) {
14 /* Prevent border-collapsing for table child elements like <div> */
15 border-collapse: separate;
16}
17
18th {
19 text-align: left;
20}
21
22
23div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
24 background-color: transparent;
25}
26div.codeBox {
27 overflow: auto;
28 margin: 1em 0;
29}
30div.codeBox pre {
31 margin: 0;
32 padding: 4px;
33 border: 1px solid #999;
34 border-radius: 5px;
35 background-color: #eff8ff;
36 display: table; /* To prevent <pre>s from taking the complete available width. */
37 /*
38 When it is officially supported, use the following CSS instead of display: table
39 to prevent big <pre>s from exceeding the browser window:
40 max-width: available;
41 width: min-content;
42 */
43}
44
45div.codeBox pre.wrap {
46 white-space: pre-wrap;
47}
48
49
50table.defaultTable tr, table.detail-table tr {
51 border: 1px solid #CCC;
52}
53
54table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
55 background-color: #FAFBFF;
56}
57
58table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
59 background-color: #EEEFFF;
60}
61
62table.defaultTable th, table.detail-table th {
63 background-color: #88b;
64 color: #fff;
65}
66
67table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
68 padding: 5px 8px;
69}
70
71
72p.notice {
73 border: 1px solid rgb(255, 0, 0);
74 background-color: rgb(238, 238, 238);
75 color: rgb(0, 51, 102);
76 padding: 0.5em;
77 margin: 1em 2em 1em 1em;
78}
79</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="
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]80 The Apache Tomcat Servlet/JSP Container
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]81 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></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="index.html">Config Ref. 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>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>web.xml</strong></p><ul><li><a href="filter.html">Filter</a></li></ul><p><strong>Other</strong></p><ul><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>The Realm Component</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>
82<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#JDBC_Database_Realm_-_org.apache.catalina.realm.JDBCRealm">JDBC Database Realm - org.apache.catalina.realm.JDBCRealm</a></li><li><a href="#DataSource_Database_Realm_-_org.apache.catalina.realm.DataSourceRealm">DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm</a></li><li><a href="#JNDI_Directory_Realm_-_org.apache.catalina.realm.JNDIRealm">JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm</a></li><li><a href="#UserDatabase_Realm_-_org.apache.catalina.realm.UserDatabaseRealm">UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm</a></li><li><a href="#Memory_Based_Realm_-_org.apache.catalina.realm.MemoryRealm">Memory Based Realm - org.apache.catalina.realm.MemoryRealm</a></li><li><a href="#JAAS_Realm_-_org.apache.catalina.realm.JAASRealm">JAAS Realm - org.apache.catalina.realm.JAASRealm</a></li><li><a href="#Combined_Realm_-_org.apache.catalina.realm.CombinedRealm">Combined Realm - org.apache.catalina.realm.CombinedRealm</a></li><li><a href="#LockOut_Realm_-_org.apache.catalina.realm.LockOutRealm">LockOut Realm - org.apache.catalina.realm.LockOutRealm</a></li><li><a href="#Null_Realm_-_org.apache.catalina.realm.NullRealm">Null Realm - org.apache.catalina.realm.NullRealm</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a></li></ul>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]83</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
84
85 <p>A <strong>Realm</strong> element represents a "database" of usernames,
86 passwords, and <em>roles</em> (similar to Unix <em>groups</em>) assigned
87 to those users. Different implementations of Realm allow Catalina to be
88 integrated into environments where such authentication information is already
89 being created and maintained, and then utilize that information to implement
90 <em>Container Managed Security</em> as described in the Servlet
91 Specification.</p>
92
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]93 <p>A Catalina container (<a href="engine.html">Engine</a>,
94 <a href="host.html">Host</a>, or <a href="context.html">Context</a>) may
95 contain no more than one Realm element (although if supported by the Realm
96 this one Realm may itself contain multiple nested Realms). In addition, the
97 Realm associated with an Engine or a Host is automatically inherited by
98 lower-level containers unless the lower level container explicitly defines its
99 own Realm. If no Realm is configured for the Engine, an instance of the
100 <a href="#Null_Realm_-_org.apache.catalina.realm.NullRealm">Null Realm</a>
101 will be configured for the Engine automatically.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]102
103 <p>For more in-depth information about container managed security in web
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]104 applications, as well as more information on configuring and using the
105 standard realm component implementations, please see the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]106 <a href="../realm-howto.html">Container-Managed Security Guide</a>.
107 </p>
108
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]109 <p><em>The description below uses the variable name $CATALINA_BASE to refer the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]110 base directory against which most relative paths are resolved. If you have
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]111 not configured Tomcat for multiple instances by setting a CATALINA_BASE
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]112 directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]113 the directory into which you have installed Tomcat.</em></p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]114
115</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
116
117 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>
118
119 <p>All implementations of <strong>Realm</strong>
120 support the following attributes:</p>
121
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]122 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]123 <p>Java class name of the implementation to use. This class must
124 implement the <code>org.apache.catalina.Realm</code> interface.</p>
125 </td></tr></table>
126
127 <p>Unlike most Catalina components, there are several standard
128 <strong>Realm</strong> implementations available. As a result,
129 the <code>className</code> attribute MUST be used to select the
130 implementation you wish to use.</p>
131
132 </blockquote></td></tr></table>
133
134
135 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JDBC Database Realm - org.apache.catalina.realm.JDBCRealm"><!--()--></a><a name="JDBC_Database_Realm_-_org.apache.catalina.realm.JDBCRealm"><strong>JDBC Database Realm - org.apache.catalina.realm.JDBCRealm</strong></a></font></td></tr><tr><td><blockquote>
136
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]137 <p>The <strong>JDBC Database Realm</strong> connects Tomcat to
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]138 a relational database, accessed through an appropriate JDBC driver,
139 to perform lookups of usernames, passwords, and their associated
140 roles. Because the lookup is done each time that it is required,
141 changes to the database will be immediately reflected in the
142 information used to authenticate new logins.</p>
143
144 <p>A rich set of additional attributes lets you configure the required
145 connection to the underlying database, as well as the table and
146 column names used to retrieve the required information:</p>
147
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]148 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]149 <p>This attribute controls how the special role name <code>*</code> is
150 handled when processing authorization constraints in web.xml. By
151 default, the specification compliant value of <code>strict</code> is
152 used which means that the user must be assigned one of the roles defined
153 in web.xml. The alternative values are <code>authOnly</code> which means
154 that the user must be authenticated but no check is made for assigned
155 roles and <code>strictAuthOnly</code> which means that the user must be
156 authenticated and no check will be made for assigned roles unless roles
157 are defined in web.xml in which case the user must be assigned at least
158 one of those roles.</p>
159 <p>When this attribute has the value of <code>authOnly</code> or
160 <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and
161 <strong>userRoleTable</strong> attributes become optional. If those two
162 attributes are omitted, the user's roles will not be loaded by this
163 Realm.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]164 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionName</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]165 <p>The database username to use when establishing the JDBC
166 connection.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]167 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionPassword</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]168 <p>The database password to use when establishing the JDBC
169 connection.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]170 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionURL</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]171 <p>The connection URL to be passed to the JDBC driver when
172 establishing a database connection.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]173 </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]174 <p>The name of the <code>MessageDigest</code> algorithm used
175 to encode user passwords stored in the database. If not specified,
176 user passwords are assumed to be stored in clear-text.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]177 </td></tr><tr><td align="left" valign="center"><code class="attributeName">digestEncoding</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]178 <p>The charset for encoding digests. If not specified, the platform
179 default will be used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]180 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">driverName</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]181 <p>Fully qualified Java class name of the JDBC driver to be
182 used to connect to the authentication database.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]183 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleNameCol</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]184 <p>Name of the column, in the "user roles" table, which contains
185 a role name assigned to the corresponding user.</p>
186 <p>This attribute is <strong>required</strong> in majority of
187 configurations. See <strong>allRolesMode</strong> attribute for
188 a rare case when it can be omitted.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]189 </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
190 <p>When processing users authenticated via the GSS-API, this attribute
191 controls if any "@..." is removed from the end of the user
192 name. If not specified, the default is <code>true</code>.</p>
193 </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
194 <p>The HTTP status code to use when the container needs to issue an HTTP
195 redirect to meet the requirements of a configured transport
196 guarantee. The provided status code is not validated. If not
197 specified, the default value of <code>302</code> is used.</p>
198 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userCredCol</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]199 <p>Name of the column, in the "users" table, which contains
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]200 the user's credentials (i.e. password). If a value for the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]201 <code>digest</code> attribute is specified, this component
202 will assume that the passwords have been encoded with the
203 specified algorithm. Otherwise, they will be assumed to be
204 in clear text.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]205 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userNameCol</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]206 <p>Name of the column, in the "users" and "user roles" table,
207 that contains the user's username.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]208 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleTable</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]209 <p>Name of the "user roles" table, which must contain columns
210 named by the <code>userNameCol</code> and <code>roleNameCol</code>
211 attributes.</p>
212 <p>This attribute is <strong>required</strong> in majority of
213 configurations. See <strong>allRolesMode</strong> attribute for
214 a rare case when it can be omitted.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]215 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userTable</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]216 <p>Name of the "users" table, which must contain columns named
217 by the <code>userNameCol</code> and <code>userCredCol</code>
218 attributes.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]219 </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]220 <p>When using X509 client certificates, this specifies the class name
221 that will be used to retrieve the user name from the certificate.
222 The class must implement the
223 <code>org.apache.catalina.realm.X509UsernameRetriever</code>
224 interface. The default is to use the certificate's SubjectDN
225 as the username.</p>
226 </td></tr></table>
227
228 <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
229 information on setting up container managed security using the
230 JDBC Database Realm component.</p>
231
232 </blockquote></td></tr></table>
233
234
235 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm"><!--()--></a><a name="DataSource_Database_Realm_-_org.apache.catalina.realm.DataSourceRealm"><strong>DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm</strong></a></font></td></tr><tr><td><blockquote>
236
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]237 <p>The <strong>DataSource Database Realm</strong> connects Tomcat to
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]238 a relational database, accessed through a JNDI named JDBC DataSource
239 to perform lookups of usernames, passwords, and their associated
240 roles. Because the lookup is done each time that it is required,
241 changes to the database will be immediately reflected in the
242 information used to authenticate new logins.</p>
243
244 <p>The JDBC Realm uses a single db connection. This requires that
245 realm based authentication be synchronized, i.e. only one authentication
246 can be done at a time. This could be a bottleneck for applications
247 with high volumes of realm based authentications.</p>
248
249 <p>The DataSource Database Realm supports simultaneous realm based
250 authentications and allows the underlying JDBC DataSource to
251 handle optimizations like database connection pooling.</p>
252
253 <p>A rich set of additional attributes lets you configure the name
254 of the JNDI JDBC DataSource, as well as the table and
255 column names used to retrieve the required information:</p>
256
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]257 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]258 <p>This attribute controls how the special role name <code>*</code> is
259 handled when processing authorization constraints in web.xml. By
260 default, the specification compliant value of <code>strict</code> is
261 used which means that the user must be assigned one of the roles defined
262 in web.xml. The alternative values are <code>authOnly</code> which means
263 that the user must be authenticated but no check is made for assigned
264 roles and <code>strictAuthOnly</code> which means that the user must be
265 authenticated and no check will be made for assigned roles unless roles
266 are defined in web.xml in which case the user must be assigned at least
267 one of those roles.</p>
268 <p>When this attribute has the value of <code>authOnly</code> or
269 <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and
270 <strong>userRoleTable</strong> attributes become optional. If those two
271 attributes are omitted, the user's roles will not be loaded by this
272 Realm.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]273 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">dataSourceName</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]274 <p>The name of the JNDI JDBC DataSource for this Realm.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]275 </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]276 <p>The name of the <code>MessageDigest</code> algorithm used
277 to encode user passwords stored in the database. If not specified,
278 user passwords are assumed to be stored in clear-text.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]279 </td></tr><tr><td align="left" valign="center"><code class="attributeName">localDataSource</code></td><td align="left" valign="center">
280 <p>When the realm is nested inside a Context element, this allows the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]281 realm to use a DataSource defined for the Context rather than a global
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]282 DataSource. If not specified, the default is <code>false</code>: use a
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]283 global DataSource.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]284 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleNameCol</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]285 <p>Name of the column, in the "user roles" table, which contains
286 a role name assigned to the corresponding user.</p>
287 <p>This attribute is <strong>required</strong> in majority of
288 configurations. See <strong>allRolesMode</strong> attribute for
289 a rare case when it can be omitted.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]290 </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
291 <p>The HTTP status code to use when the container needs to issue an HTTP
292 redirect to meet the requirements of a configured transport
293 guarantee. The provided status code is not validated. If not
294 specified, the default value of <code>302</code> is used.</p>
295 </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
296 <p>When processing users authenticated via the GSS-API, this attribute
297 controls if any "@..." is removed from the end of the user
298 name. If not specified, the default is <code>true</code>.</p>
299 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userCredCol</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]300 <p>Name of the column, in the "users" table, which contains
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]301 the user's credentials (i.e. password). If a value for the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]302 <code>digest</code> attribute is specified, this component
303 will assume that the passwords have been encoded with the
304 specified algorithm. Otherwise, they will be assumed to be
305 in clear text.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]306 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userNameCol</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]307 <p>Name of the column, in the "users" and "user roles" table,
308 that contains the user's username.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]309 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleTable</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]310 <p>Name of the "user roles" table, which must contain columns
311 named by the <code>userNameCol</code> and <code>roleNameCol</code>
312 attributes.</p>
313 <p>This attribute is <strong>required</strong> in majority of
314 configurations. See <strong>allRolesMode</strong> attribute for
315 a rare case when it can be omitted.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]316 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userTable</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]317 <p>Name of the "users" table, which must contain columns named
318 by the <code>userNameCol</code> and <code>userCredCol</code>
319 attributes.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]320 </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]321 <p>When using X509 client certificates, this specifies the class name
322 that will be used to retrieve the user name from the certificate.
323 The class must implement the
324 <code>org.apache.catalina.realm.X509UsernameRetriever</code>
325 interface. The default is to use the certificate's SubjectDN
326 as the username.</p>
327 </td></tr></table>
328
329 <p>See the <a href="../realm-howto.html#DataSourceRealm">
330 DataSource Realm HOW-TO</a> for more information on setting up container
331 managed security using the DataSource Database Realm component.</p>
332
333 </blockquote></td></tr></table>
334
335
336 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm"><!--()--></a><a name="JNDI_Directory_Realm_-_org.apache.catalina.realm.JNDIRealm"><strong>JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm</strong></a></font></td></tr><tr><td><blockquote>
337
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]338 <p>The <strong>JNDI Directory Realm</strong> connects Tomcat to
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]339 an LDAP Directory, accessed through an appropriate JNDI driver,
340 that stores usernames, passwords, and their associated
341 roles. Changes to the directory are immediately reflected in the
342 information used to authenticate new logins.</p>
343
344
345 <p>The directory realm supports a variety of approaches to using
346 LDAP for authentication:</p>
347
348 <ul>
349 <li>The realm can either use a pattern to determine the
350 distinguished name (DN) of the user's directory entry, or search
351 the directory to locate that entry.
352 </li>
353
354 <li>The realm can authenticate the user either by binding to the
355 directory with the DN of the user's entry and the password
356 presented by the user, or by retrieving the password from the
357 user's entry and performing a comparison locally.
358 </li>
359
360 <li>Roles may be represented in the directory as explicit entries
361 found by a directory search (e.g. group entries of which the user
362 is a member), as the values of an attribute in the user's entry,
363 or both.
364 </li>
365 </ul>
366
367 <p> A rich set of additional attributes lets you configure the
368 required behaviour as well as the connection to the underlying
369 directory and the element and attribute names used to retrieve
370 information from the directory:</p>
371
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]372 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">adCompat</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]373 <p>Microsoft Active Directory often returns referrals.
374 When iterating over NamingEnumerations these lead to
375 PartialResultExceptions. If you want us to ignore those exceptions,
376 set this attribute to "true". Unfortunately there's no stable way
377 to detect, if the Exceptions really come from an AD referral.
378 The default value is "false".</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]379 </td></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]380 <p>This attribute controls how the special role name <code>*</code> is
381 handled when processing authorization constraints in web.xml. By
382 default, the specification compliant value of <code>strict</code> is
383 used which means that the user must be assigned one of the roles defined
384 in web.xml. The alternative values are <code>authOnly</code> which means
385 that the user must be authenticated but no check is made for assigned
386 roles and <code>strictAuthOnly</code> which means that the user must be
387 authenticated and no check will be made for assigned roles unless roles
388 are defined in web.xml in which case the user must be assigned at least
389 one of those roles.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]390 </td></tr><tr><td align="left" valign="center"><code class="attributeName">alternateURL</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]391 <p>If a socket connection can not be made to the provider at
392 the <code>connectionURL</code> an attempt will be made to use the
393 <code>alternateURL</code>.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]394 </td></tr><tr><td align="left" valign="center"><code class="attributeName">authentication</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]395 <p>A string specifying the type of authentication to use.
396 "none", "simple", "strong" or a provider specific definition
397 can be used. If no value is given the providers default is used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]398 </td></tr><tr><td align="left" valign="center"><code class="attributeName">cipherSuites</code></td><td align="left" valign="center">
399 <p>Specify which cipher suites are allowed when trying to open
400 a secured connection using StartTLS. The allowed cipher suites
401 are specified by a comma separated list. The default is to use the
402 cipher suites of the JVM.</p>
403 </td></tr><tr><td align="left" valign="center"><code class="attributeName">commonRole</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]404 <p>A role name assigned to each successfully authenticated user in
405 addition to the roles retrieved from LDAP. If not specified, only
406 the roles retrieved via LDAP are used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]407 </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]408 <p>The directory username to use when establishing a
409 connection to the directory for LDAP search operations. If not
410 specified an anonymous connection is made, which is often
411 sufficient unless you specify the <code>userPassword</code>
412 property.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]413 </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionPassword</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]414 <p>The directory password to use when establishing a
415 connection to the directory for LDAP search operations. If not
416 specified an anonymous connection is made, which is often
417 sufficient unless you specify the <code>userPassword</code>
418 property.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]419 </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionTimeout</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]420 <p>The timeout in milliseconds to use when establishing the connection
421 to the LDAP directory. If not specified, a value of 5000 (5 seconds) is
422 used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]423 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionURL</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]424 <p>The connection URL to be passed to the JNDI driver when
425 establishing a connection to the directory.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]426 </td></tr><tr><td align="left" valign="center"><code class="attributeName">contextFactory</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]427 <p>Fully qualified Java class name of the factory class used
428 to acquire our JNDI <code>InitialContext</code>. By default,
429 assumes that the standard JNDI LDAP provider will be utilized.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]430 </td></tr><tr><td align="left" valign="center"><code class="attributeName">derefAliases</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]431 <p>A string specifying how aliases are to be dereferenced during
432 search operations. The allowed values are "always", "never",
433 "finding" and "searching". If not specified, "always" is used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]434 </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]435 <p>The digest algorithm to apply to the plaintext password offered
436 by the user before comparing it with the value retrieved from the
437 directory. Valid values are those accepted for the algorithm name
438 by the <code>java.security.MessageDigest</code> class. If not
439 specified the plaintext password is assumed to be retrieved. Not
440 required unless <code>userPassword</code> is specified</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]441 </td></tr><tr><td align="left" valign="center"><code class="attributeName">hostnameVerifierClassName</code></td><td align="left" valign="center">
442 <p>The name of the class to use for hostname verification when
443 using StartTLS for securing the connection to the ldap server.
444 The default constructor will be used to construct an instance of
445 the verifier class. The default is to accept only those hostnames,
446 that are valid according to the peer certificate of the ldap
447 server.</p>
448 </td></tr><tr><td align="left" valign="center"><code class="attributeName">protocol</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]449 <p>A string specifying the security protocol to use. If not given
450 the providers default is used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]451 </td></tr><tr><td align="left" valign="center"><code class="attributeName">referrals</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]452 <p>How do we handle JNDI referrals? Allowed values are
453 "ignore", "follow", or "throw" (see javax.naming.Context.REFERRAL
454 for more information).
455 Microsoft Active Directory often returns referrals.
456 If you need to follow them set referrals to "follow".
457 Caution: if your DNS is not part of AD, the LDAP client lib might try
458 to resolve your domain name in DNS to find another LDAP server.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]459 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleBase</code></td><td align="left" valign="center">
460 <p>The base directory entry for performing role searches. If not
461 specified the top-level element in the directory context will be used.
462 If specified it may optionally include pattern replacements
463 "{0}".."{n}" corresponding to the name parts of the
464 user's distinguished name (as returned by
465 <code>javax.naming.Name.get()</code>).</p>
466 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]467 <p>The name of the attribute that contains role names in the
468 directory entries found by a role search. In addition you can
469 use the <code>userRoleName</code> property to specify the name
470 of an attribute, in the user's entry, containing additional
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]471 role names.</p>
472 <p>If <code>roleName</code> is not specified a role
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]473 search does not take place, and roles are taken only from the
474 user's entry.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]475 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleNested</code></td><td align="left" valign="center">
476 <p>Set to <code>true</code> if you want to nest roles into roles.
477 When a role search is performed and the value of this property is
478 <code>true</code>, the search will be repeated recursively to find
479 all the roles that belong to the user either directly or indirectly.
480 If not specified, the default value of <code>false</code> is used.</p>
481 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSearch</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]482 <p>The LDAP filter expression used for performing role
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]483 searches.</p>
484
485 <p>Use <code>{0}</code> to substitute the distinguished name (DN)
486 of the user, and/or <code>{1}</code> to substitute the username,
487 and/or <code>{2}</code> for the value of an attribute from the
488 user's directory entry, of the authenticated user.
489 The name of the attribute that provides the value for <code>{2}</code>
490 is configured by the <code>userRoleAttribute</code> property.</p>
491
492 <p>When <code>roleNested</code> property is <code>true</code>,
493 this filter expression will be also used to recursively search for
494 other roles, which indirectly belong to this user. To find the
495 roles that match the newly found role, the following values
496 are used:
497 <code>{0}</code> is substituted by the distinguished name of the newly
498 found role, and both <code>{1}</code> and <code>{2}</code> are
499 substituted by the name of the role (see the <code>roleName</code>
500 property). The <code>userRoleAttribute</code> property is not
501 applicable to this search.</p>
502
503 <p>If this property is not specified, a role search does not take
504 place and roles are taken only from the attribute in the user's entry
505 specified by the <code>userRoleName</code> property.</p>
506 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSearchAsUser</code></td><td align="left" valign="center">
507 <p> When searching for user roles, should the search be performed as the
508 user currently being authenticated? If false,
509 <code>connectionName</code> and <code>connectionPassword</code> will be
510 used if specified, else an anonymous. If not specified, the default
511 value of <code>false</code> is used. Note that when accessing the
512 directory using delegated credentials, this attribute is always ignored
513 and the search is performed using the delegated credentials.</p>
514 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSubtree</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]515 <p>Set to <code>true</code> if you want to search the entire
516 subtree of the element specified by the <code>roleBase</code>
517 property for role entries associated with the user. The
518 default value of <code>false</code> causes only the top level
519 to be searched.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]520 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sizeLimit</code></td><td align="left" valign="center">
521 <p>Specifies the maximum number of records to return when using the
522 <code>userSearch</code> attribute. If not specified, the default of
523 <code>0</code> is used which indicates no limit.</p>
524 </td></tr><tr><td align="left" valign="center"><code class="attributeName">spnegoDelegationQop</code></td><td align="left" valign="center">
525 <p>When the JNDI Realm is used with the SPNEGO authenticator and
526 <code>useDelegatedCredential</code> is <code>true</code> this attribute
527 controls the QOP (Quality of Protection) that should be used for
528 the connection to the LDAP
529 server after authentication. This value is used to set the
530 <code>javax.security.sasl.qop</code> environment property for the LDAP
531 connection. This attribute should be a comma-separated list of values
532 selected from <code>auth-conf</code>, <code>auth-int</code> and
533 <code>auth</code>. See <a href="http://docs.oracle.com/javase/7/docs/api/javax/security/sasl/Sasl.html#QOP" rel="nofollow">Java documentation</a> for more details.</p>
534 <p>The default value is <code>auth-conf</code>.</p>
535 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sslProtocol</code></td><td align="left" valign="center">
536 <p>Specifies which ssl protocol should be used, when connecting with
537 StartTLS. The default is to let the jre decide. If you need even more
538 control, you can specify the <code>SSLSocketFactory</code> to use.</p>
539 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sslSocketFactory</code></td><td align="left" valign="center">
540 <p>Specifies which <code>SSLSocketFactory</code> to use when connecting
541 to the ldap server using StartTLS. An instance of the class will be
542 constructed using the default constructor. If none class name is given
543 the default jre <code>SSLSocketFactory</code> will be used.</p>
544 </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
545 <p>When processing users authenticated via the GSS-API, this attribute
546 controls if any "@..." is removed from the end of the user
547 name. If not specified, the default is <code>true</code>.</p>
548 </td></tr><tr><td align="left" valign="center"><code class="attributeName">timeLimit</code></td><td align="left" valign="center">
549 <p>Specifies the time (in milliseconds) to wait for records to be
550 returned when using the <code>userSearch</code> attribute. If not
551 specified, the default of <code>0</code> is used which indicates no
552 limit.</p>
553 </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
554 <p>The HTTP status code to use when the container needs to issue an HTTP
555 redirect to meet the requirements of a configured transport
556 guarantee. The provided status code is not validated. If not
557 specified, the default value of <code>302</code> is used.</p>
558 </td></tr><tr><td align="left" valign="center"><code class="attributeName">useDelegatedCredential</code></td><td align="left" valign="center">
559 <p>When the JNDIRealm is used with the SPNEGO authenticator, delegated
560 credentials for the user may be available. If such credentials are
561 present, this attribute controls whether or not they are used to
562 connect to the directory. If not specified, the default value of
563 <code>true</code> is used.</p>
564 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userBase</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]565 <p>The base element for user searches performed using the
566 <code>userSearch</code> expression. Not used if you are using
567 the <code>userPattern</code> expression.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]568 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userPassword</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]569 <p>Name of the attribute in the user's entry containing the
570 user's password. If you specify this value, JNDIRealm will
571 bind to the directory using the values specified by
572 <code>connectionName</code> and
573 <code>connectionPassword</code> properties, and retrieve the
574 corresponding attribute for comparison to the value specified
575 by the user being authenticated. If you do
576 <strong>not</strong> specify this value, JNDIRealm will
577 attempt a simple bind to the directory using the DN of the
578 user's entry and the password presented by the user, with a
579 successful bind being interpreted as an authenticated
580 user.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]581 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userPattern</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]582 <p>Pattern for the distinguished name (DN) of the user's
583 directory entry, with <code>{0}</code> marking where the
584 actual username should be inserted. You can use this property
585 instead of <code>userSearch</code>, <code>userSubtree</code>
586 and <code>userBase</code> when the distinguished name contains
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]587 the username and is otherwise the same for all users. Note that
588 when accessing the directory using delegated credentials, this
589 attribute is always ignored and <code>userSearch</code>,
590 <code>userSubtree</code> and <code>userBase</code> are always
591 used instead.</p>
592 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]593 <p>The name of an attribute in the user's directory entry
594 containing zero or more values for the names of roles assigned
595 to this user. In addition you can use the
596 <code>roleName</code> property to specify the name of an
597 attribute to be retrieved from individual role entries found
598 by searching the directory. If <code>userRoleName</code> is
599 not specified all the roles for a user derive from the role
600 search.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]601 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleAttribute</code></td><td align="left" valign="center">
602 <p>The name of an attribute in the user's directory entry
603 containing the value that you wish to use when you search for
604 roles. This is especially useful for RFC 2307 where
605 the role memberUid can be the <code>uid</code> or the
606 <code>uidNumber</code> of the user. This value will be
607 marked as <code>{2}</code> in your role search filter expression.
608 This value will NOT be available for nested role searches.</p>
609 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userSearch</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]610 <p>The LDAP filter expression to use when searching for a
611 user's directory entry, with <code>{0}</code> marking where
612 the actual username should be inserted. Use this property
613 (along with the <code>userBase</code> and
614 <code>userSubtree</code> properties) instead of
615 <code>userPattern</code> to search the directory for the
616 user's entry.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]617 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userSearchAsUser</code></td><td align="left" valign="center">
618 <p> When searching for a user's entry, should the search be performed as
619 the user currently being authenticated? If false,
620 <code>connectionName</code> and <code>connectionPassword</code> will be
621 used if specified, else an anonymous. If not specified, the default
622 value of <code>false</code> is used. Note that when accessing the
623 directory using delegated credentials, this attribute is always ignored
624 and the search is performed using the delegated credentials.</p>
625 </td></tr><tr><td align="left" valign="center"><code class="attributeName">userSubtree</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]626 <p>Set to <code>true</code> if you want to search the entire
627 subtree of the element specified by the <code>userBase</code>
628 property for the user's entry. The default value of
629 <code>false</code> causes only the top level to be searched.
630 Not used if you are using the <code>userPattern</code>
631 expression.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]632 </td></tr><tr><td align="left" valign="center"><code class="attributeName">useStartTls</code></td><td align="left" valign="center">
633 <p>Set to <code>true</code> if you want to use StartTLS for securing
634 the connection to the ldap server. The default value is <code>false</code>.
635 </p>
636 </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]637 <p>When using X509 client certificates, this specifies the class name
638 that will be used to retrieve the user name from the certificate.
639 The class must implement the
640 <code>org.apache.catalina.realm.X509UsernameRetriever</code>
641 interface. The default is to use the certificate's SubjectDN
642 as the username.</p>
643 </td></tr></table>
644
645 <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
646 information on setting up container managed security using the
647 JNDI Directory Realm component.</p>
648
649 </blockquote></td></tr></table>
650
651
652 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm"><!--()--></a><a name="UserDatabase_Realm_-_org.apache.catalina.realm.UserDatabaseRealm"><strong>UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm</strong></a></font></td></tr><tr><td><blockquote>
653
654 <p>The <strong>UserDatabase Realm</strong> is a Realm implementation
655 that is based on a UserDatabase resource made available through the global
656 JNDI resources configured for this Tomcat instance.</p>
657
658 <p>The UserDatabase Realm implementation supports the following
659 additional attributes:</p>
660
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]661 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]662 <p>This attribute controls how the special role name <code>*</code> is
663 handled when processing authorization constraints in web.xml. By
664 default, the specification compliant value of <code>strict</code> is
665 used which means that the user must be assigned one of the roles defined
666 in web.xml. The alternative values are <code>authOnly</code> which means
667 that the user must be authenticated but no check is made for assigned
668 roles and <code>strictAuthOnly</code> which means that the user must be
669 authenticated and no check will be made for assigned roles unless roles
670 are defined in web.xml in which case the user must be assigned at least
671 one of those roles.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]672 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">resourceName</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]673 <p>The name of the global <code>UserDatabase</code> resource
674 that this realm will use for user, password and role information.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]675 </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
676 <p>The HTTP status code to use when the container needs to issue an HTTP
677 redirect to meet the requirements of a configured transport
678 guarantee. The provided status code is not validated. If not
679 specified, the default value of <code>302</code> is used.</p>
680 </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]681 <p>When using X509 client certificates, this specifies the class name
682 that will be used to retrieve the user name from the certificate.
683 The class must implement the
684 <code>org.apache.catalina.realm.X509UsernameRetriever</code>
685 interface. The default is to use the certificate's SubjectDN
686 as the username.</p>
687 </td></tr></table>
688
689 <p>See the
690 <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
691 information on setting up container managed security using the UserDatabase
692 Realm component and the
693 <a href="../jndi-resources-howto.html">JNDI resources how-to</a> for more
694 information on how to configure a UserDatabase resource.</p>
695
696 </blockquote></td></tr></table>
697
698
699 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Memory Based Realm - org.apache.catalina.realm.MemoryRealm"><!--()--></a><a name="Memory_Based_Realm_-_org.apache.catalina.realm.MemoryRealm"><strong>Memory Based Realm - org.apache.catalina.realm.MemoryRealm</strong></a></font></td></tr><tr><td><blockquote>
700
701 <p>The <strong>Memory Based Realm</strong> is a simple Realm implementation
702 that reads user information from an XML format, and represents it as a
703 collection of Java objects in memory. This implementation is intended
704 solely to get up and running with container managed security - it is NOT
705 intended for production use. As such, there are no mechanisms for
706 updating the in-memory collection of users when the content of the
707 underlying data file is changed.</p>
708
709 <p>The Memory Based Realm implementation supports the following
710 additional attributes:</p>
711
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]712 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]713 <p>This attribute controls how the special role name <code>*</code> is
714 handled when processing authorization constraints in web.xml. By
715 default, the specification compliant value of <code>strict</code> is
716 used which means that the user must be assigned one of the roles defined
717 in web.xml. The alternative values are <code>authOnly</code> which means
718 that the user must be authenticated but no check is made for assigned
719 roles and <code>strictAuthOnly</code> which means that the user must be
720 authenticated and no check will be made for assigned roles unless roles
721 are defined in web.xml in which case the user must be assigned at least
722 one of those roles.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]723 </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]724 <p>The digest algorithm used to store passwords in non-plaintext
725 formats. Valid values are those accepted for the algorithm name by the
726 <code>java.security.MessageDigest</code> class. If not specified,
727 passwords are stored in clear text.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]728 </td></tr><tr><td align="left" valign="center"><code class="attributeName">pathname</code></td><td align="left" valign="center">
729 <p>URL, absolute path or relative path (to $CATALINA_BASE) for the XML
730 file containing our user information. See below for details on the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]731 XML element format required. If no pathname is specified, the
732 default value is <code>conf/tomcat-users.xml</code>.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]733 </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
734 <p>When processing users authenticated via the GSS-API, this attribute
735 controls if any "@..." is removed from the end of the user
736 name. If not specified, the default is <code>true</code>.</p>
737 </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
738 <p>The HTTP status code to use when the container needs to issue an HTTP
739 redirect to meet the requirements of a configured transport
740 guarantee. The provided status code is not validated. If not
741 specified, the default value of <code>302</code> is used.</p>
742 </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]743 <p>When using X509 client certificates, this specifies the class name
744 that will be used to retrieve the user name from the certificate.
745 The class must implement the
746 <code>org.apache.catalina.realm.X509UsernameRetriever</code>
747 interface. The default is to use the certificate's SubjectDN
748 as the username.</p>
749 </td></tr></table>
750
751 <p>The XML document referenced by the <code>pathname</code> attribute must
752 conform to the following requirements:</p>
753 <ul>
754 <li>The root (outer) element must be <code>&lt;tomcat-users&gt;</code>.
755 </li>
756 <li>Each authorized user must be represented by a single XML element
757 <code>&lt;user&gt;</code>, nested inside the root element.</li>
758 <li>Each <code>&lt;user&gt;</code> element must have the following
759 attributes:
760 <ul>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]761 <li><strong>username</strong> - Username of this user (must be unique
762 within this file).<br>
763 For compatibility, it is allowed to use <strong>name</strong> as an
764 alternative name for this attribute.</li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]765 <li><strong>password</strong> - Password of this user (in
766 clear text).</li>
767 <li><strong>roles</strong> - Comma-delimited list of the role names
768 assigned to this user.</li>
769 </ul></li>
770 </ul>
771
772 <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
773 information on setting up container managed security using the
774 Memory Based Realm component.</p>
775
776 </blockquote></td></tr></table>
777
778
779 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JAAS Realm - org.apache.catalina.realm.JAASRealm"><!--()--></a><a name="JAAS_Realm_-_org.apache.catalina.realm.JAASRealm"><strong>JAAS Realm - org.apache.catalina.realm.JAASRealm</strong></a></font></td></tr><tr><td><blockquote>
780
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]781 <p><strong>JAASRealm</strong> is an implementation of the Tomcat
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]782 <code>Realm</code> interface that authenticates users through the Java
783 Authentication &amp; Authorization Service (JAAS) framework which is now
784 provided as part of the standard J2SE API.</p>
785
786 <p>Using JAASRealm gives the developer the ability to combine practically
787 any conceivable security realm with Tomcat's CMA.</p>
788
789 <p>JAASRealm is prototype for Tomcat of the JAAS-based J2EE authentication
790 framework for J2EE v1.4, based on the <a href="http://www.jcp.org/en/jsr/detail?id=196">JCP Specification Request
791 196</a> to enhance container-managed security and promote 'pluggable'
792 authentication mechanisms whose implementations would be
793 container-independent.</p>
794
795 <p>Based on the JAAS login module and principal
796 (see <code>javax.security.auth.spi.LoginModule</code> and
797 <code>javax.security.Principal</code>), you can develop your own security
798 mechanism or wrap another third-party mechanism for integration with the CMA
799 as implemented by Tomcat.</p>
800
801 <p>The JAAS Realm implementation supports the following additional
802 attributes:</p>
803
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]804 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]805 <p>This attribute controls how the special role name <code>*</code> is
806 handled when processing authorization constraints in web.xml. By
807 default, the specification compliant value of <code>strict</code> is
808 used which means that the user must be assigned one of the roles defined
809 in web.xml. The alternative values are <code>authOnly</code> which means
810 that the user must be authenticated but no check is made for assigned
811 roles and <code>strictAuthOnly</code> which means that the user must be
812 authenticated and no check will be made for assigned roles unless roles
813 are defined in web.xml in which case the user must be assigned at least
814 one of those roles.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]815 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">appName</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]816 <p>The name of the application as configured in your login configuration
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]817 file
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]818 (<a href="http://docs.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS LoginConfig</a>).</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]819 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userClassNames</code></strong></td><td align="left" valign="center">
820 <p>A comma-separated list of the names of the classes that you have made
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]821 for your user <code>Principals</code>.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]822 </td></tr><tr><td align="left" valign="center"><code class="attributeName">configFile</code></td><td align="left" valign="center">
823 <p>The name of a JAAS configuration file to use with this Realm. It will
824 be searched for using <code>ClassLoader#getResource(String)</code> so it
825 is possible for the configuration to be bundled within a web
826 application. If not specified, the default JVM global JAAS configuration
827 will be used.</p>
828 </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleClassNames</code></td><td align="left" valign="center">
829 <p>A comma-separated list of the names of the classes that you have made
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]830 for your role <code>Principals</code>.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]831 </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
832 <p>When processing users authenticated via the GSS-API, this attribute
833 controls if any "@..." is removed from the end of the user
834 name. If not specified, the default is <code>true</code>.</p>
835 </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
836 <p>The HTTP status code to use when the container needs to issue an HTTP
837 redirect to meet the requirements of a configured transport
838 guarantee. The provided status code is not validated. If not
839 specified, the default value of <code>302</code> is used.</p>
840 </td></tr><tr><td align="left" valign="center"><code class="attributeName">useContextClassLoader</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]841 <p>Instructs JAASRealm to use the context class loader for loading the
842 user-specified <code>LoginModule</code> class and associated
843 <code>Principal</code> classes. The default value is <code>true</code>,
844 which is backwards-compatible with the way Tomcat 5 works. To load
845 classes using the container's classloader, specify
846 <code>false</code>.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]847 </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]848 <p>When using X509 client certificates, this specifies the class name
849 that will be used to retrieve the user name from the certificate.
850 The class must implement the
851 <code>org.apache.catalina.realm.X509UsernameRetriever</code>
852 interface. The default is to use the certificate's SubjectDN
853 as the username.</p>
854 </td></tr></table>
855
856 <p>See the <a href="../realm-howto.html">Container-Managed Security
857 Guide</a> for more information on setting up container managed security
858 using the JAAS Realm component.</p>
859
860 </blockquote></td></tr></table>
861
862
863 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Combined Realm - org.apache.catalina.realm.CombinedRealm"><!--()--></a><a name="Combined_Realm_-_org.apache.catalina.realm.CombinedRealm"><strong>Combined Realm - org.apache.catalina.realm.CombinedRealm</strong></a></font></td></tr><tr><td><blockquote>
864
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]865 <p><strong>CombinedRealm</strong> is an implementation of the Tomcat
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]866 <code>Realm</code> interface that authenticates users through one or more
867 sub-Realms.</p>
868
869 <p>Using CombinedRealm gives the developer the ability to combine multiple
870 Realms of the same or different types. This can be used to authenticate
871 against different sources, provide fall back in case one Realm fails or for
872 any other purpose that requires multiple Realms.</p>
873
874 <p>Sub-realms are defined by nesting <code>Realm</code> elements inside the
875 <code>Realm</code> element that defines the CombinedRealm. Authentication
876 will be attempted against each <code>Realm</code> in the order they are
877 listed. Authentication against any Realm will be sufficient to authenticate
878 the user.</p>
879
880 <p>See the <a href="../realm-howto.html">Container-Managed Security
881 Guide</a> for more information on setting up container managed security
882 using the CombinedRealm component.</p>
883
884 <p>The CombinedRealm implementation supports the following additional
885 attributes.</p>
886
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]887 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]888 <p>This attribute controls how the special role name <code>*</code> is
889 handled when processing authorization constraints in web.xml. By
890 default, the specification compliant value of <code>strict</code> is
891 used which means that the user must be assigned one of the roles defined
892 in web.xml. The alternative values are <code>authOnly</code> which means
893 that the user must be authenticated but no check is made for assigned
894 roles and <code>strictAuthOnly</code> which means that the user must be
895 authenticated and no check will be made for assigned roles unless roles
896 are defined in web.xml in which case the user must be assigned at least
897 one of those roles.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]898 </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
899 <p>The HTTP status code to use when the container needs to issue an HTTP
900 redirect to meet the requirements of a configured transport
901 guarantee. The provided status code is not validated. If not
902 specified, the default value of <code>302</code> is used.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]903 </td></tr></table>
904 </blockquote></td></tr></table>
905
906
907 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="LockOut Realm - org.apache.catalina.realm.LockOutRealm"><!--()--></a><a name="LockOut_Realm_-_org.apache.catalina.realm.LockOutRealm"><strong>LockOut Realm - org.apache.catalina.realm.LockOutRealm</strong></a></font></td></tr><tr><td><blockquote>
908
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]909 <p><strong>LockOutRealm</strong> is an implementation of the Tomcat
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]910 <code>Realm</code> interface that extends the CombinedRealm to provide lock
911 out functionality to provide a user lock out mechanism if there are too many
912 failed authentication attempts in a given period of time.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]913
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]914 <p>To ensure correct operation, there is a reasonable degree of
915 synchronization in this Realm.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]916
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]917 <p>This Realm does not require modification to the underlying Realms or the
918 associated user storage mechanisms. It achieves this by recording all failed
919 logins, including those for users that do not exist. To prevent a DOS by
920 deliberating making requests with invalid users (and hence causing this
921 cache to grow) the size of the list of users that have failed authentication
922 is limited.</p>
923
924 <p>Sub-realms are defined by nesting <code>Realm</code> elements inside the
925 <code>Realm</code> element that defines the LockOutRealm. Authentication
926 will be attempted against each <code>Realm</code> in the order they are
927 listed. Authentication against any Realm will be sufficient to authenticate
928 the user.</p>
929
930 <p>The LockOutRealm implementation supports the following additional
931 attributes.</p>
932
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]933 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]934 <p>This attribute controls how the special role name <code>*</code> is
935 handled when processing authorization constraints in web.xml. By
936 default, the specification compliant value of <code>strict</code> is
937 used which means that the user must be assigned one of the roles defined
938 in web.xml. The alternative values are <code>authOnly</code> which means
939 that the user must be authenticated but no check is made for assigned
940 roles and <code>strictAuthOnly</code> which means that the user must be
941 authenticated and no check will be made for assigned roles unless roles
942 are defined in web.xml in which case the user must be assigned at least
943 one of those roles.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]944 </td></tr><tr><td align="left" valign="center"><code class="attributeName">cacheRemovalWarningTime</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]945 <p>If a failed user is removed from the cache because the cache is too
946 big before it has been in the cache for at least this period of time (in
947 seconds) a warning message will be logged. Defaults to 3600 (1 hour).</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]948 </td></tr><tr><td align="left" valign="center"><code class="attributeName">cacheSize</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]949 <p>Number of users that have failed authentication to keep in cache. Over
950 time the cache will grow to this size and may not shrink. Defaults to
951 1000.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]952 </td></tr><tr><td align="left" valign="center"><code class="attributeName">failureCount</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]953 <p>The number of times in a row a user has to fail authentication to be
954 locked out. Defaults to 5.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]955 </td></tr><tr><td align="left" valign="center"><code class="attributeName">lockOutTime</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]956 <p>The time (in seconds) a user is locked out for after too many
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]957 authentication failures. Defaults to 300 (5 minutes). Further
958 authentication failures during the lock out time will cause the lock out
959 timer to reset to zero, effectively extending the lock out time. Valid
960 authentication attempts during the lock out period will not succeed but
961 will also not reset the lock out time.</p>
962 </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
963 <p>The HTTP status code to use when the container needs to issue an HTTP
964 redirect to meet the requirements of a configured transport
965 guarantee. The provided status code is not validated. If not
966 specified, the default value of <code>302</code> is used.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]967 </td></tr></table>
968
969 <p>See the <a href="../realm-howto.html">Container-Managed Security
970 Guide</a> for more information on setting up container managed security
971 using the LockOutRealm component.</p>
972
973 </blockquote></td></tr></table>
974
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]975 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Null Realm - org.apache.catalina.realm.NullRealm"><!--()--></a><a name="Null_Realm_-_org.apache.catalina.realm.NullRealm"><strong>Null Realm - org.apache.catalina.realm.NullRealm</strong></a></font></td></tr><tr><td><blockquote>
976
977 <p><strong>NullRealm</strong> is a minimal implementation of the Tomcat
978 <code>Realm</code> interface that always returns null when an attempt is
979 made to validate a user name and associated credentials. It is intended to
980 be used as a default Realm implementation when no other Realm is
981 specified.</p>
982
983 <p>The NullRealm implementation supports the following additional
984 attributes.</p>
985
986 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
987 <p>The HTTP status code to use when the container needs to issue an HTTP
988 redirect to meet the requirements of a configured transport
989 guarantee. The provided status code is not validated. If not
990 specified, the default value of <code>302</code> is used.</p>
991 </td></tr></table>
992
993 </blockquote></td></tr></table>
994
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]995</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
996
997 <h3>CombinedRealm Implementation</h3>
998
999 <p>If you are using the <em>CombinedRealm Implementation</em> or a Realm
1000 that extends the CombinedRealm, e.g. the LockOutRealm,
1001 <strong>&lt;Realm&gt;</strong> elements may be nested inside it.</p>
1002
1003 <h3>Other Realm Implementations</h3>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1004
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1005 <p>No other Realm implementation supports nested components.</p>
1006
1007</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
1008
1009 <p>See <a href="host.html">Single Sign On</a> for information about
1010 configuring Single Sign On support for a virtual host.</p>
1011
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1012</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
1013 on improving documentation for Apache Tomcat.<br><br>
1014 If you have trouble and need help, read
1015 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
1016 and ask your question on the tomcat-users
1017 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
1018 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
1019 The Apache Comments System is explained <a href="../comments.html">here</a>.
1020 Comments may be removed by our moderators if they are either
1021 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
1022 var comments_shortname = 'tomcat';
1023 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/config/realm.html';
1024 (function(w, d) {
1025 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
1026 d.write('<div id="comments_thread"><\/div>');
1027 var s = d.createElement('script');
1028 s.type = 'text/javascript';
1029 s.async = true;
1030 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
1031 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
1032 }
1033 else {
1034 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
1035 }
1036 })(window, document);
1037 //--><!]]></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>
1038 Copyright &copy; 1999-2017, Apache Software Foundation
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1039 </em></font></div></td></tr></table></body></html>