升级Tomcat版本 apache-tomcat-7.0.77
diff --git a/tomcat-cas/webapps/docs/config/realm.html b/tomcat-cas/webapps/docs/config/realm.html
index 64ca767..95c0912 100644
--- a/tomcat-cas/webapps/docs/config/realm.html
+++ b/tomcat-cas/webapps/docs/config/realm.html
@@ -1,10 +1,85 @@
-<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference (6.0.41) - The Realm Component</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
- .noPrint {display: none;}
- td#mainBody {width: 100%;}
- </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="
+<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">
+ .noPrint {display: none;}
+ td#mainBody {width: 100%;}
+</style><style type="text/css">
+code {background-color:rgb(224,255,255);padding:0 0.1em;}
+code.attributeName, code.propertyName {background-color:transparent;}
+
+
+table {
+ border-collapse: collapse;
+ text-align: left;
+}
+table *:not(table) {
+ /* Prevent border-collapsing for table child elements like <div> */
+ border-collapse: separate;
+}
+
+th {
+ text-align: left;
+}
+
+
+div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
+ background-color: transparent;
+}
+div.codeBox {
+ overflow: auto;
+ margin: 1em 0;
+}
+div.codeBox pre {
+ margin: 0;
+ padding: 4px;
+ border: 1px solid #999;
+ border-radius: 5px;
+ background-color: #eff8ff;
+ display: table; /* To prevent <pre>s from taking the complete available width. */
+ /*
+ When it is officially supported, use the following CSS instead of display: table
+ to prevent big <pre>s from exceeding the browser window:
+ max-width: available;
+ width: min-content;
+ */
+}
+
+div.codeBox pre.wrap {
+ white-space: pre-wrap;
+}
+
+
+table.defaultTable tr, table.detail-table tr {
+ border: 1px solid #CCC;
+}
+
+table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
+ background-color: #FAFBFF;
+}
+
+table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
+ background-color: #EEEFFF;
+}
+
+table.defaultTable th, table.detail-table th {
+ background-color: #88b;
+ color: #fff;
+}
+
+table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
+ padding: 5px 8px;
+}
+
+
+p.notice {
+ border: 1px solid rgb(255, 0, 0);
+ background-color: rgb(238, 238, 238);
+ color: rgb(0, 51, 102);
+ padding: 0.5em;
+ margin: 1em 2em 1em 1em;
+}
+</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="
The Apache Tomcat Servlet/JSP Container
- " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.41, May 19 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</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="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="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>Apache Tomcat Configuration Reference</h1><h2>The Realm Component</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
-<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></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a></li></ul>
+ " 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>
+<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>
</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>
<p>A <strong>Realm</strong> element represents a "database" of usernames,
@@ -15,25 +90,27 @@
<em>Container Managed Security</em> as described in the Servlet
Specification.</p>
- <p>You may nest a Realm inside any Catalina container
- <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
- <a href="context.html">Context</a>). In addition, Realms associated with
- an Engine or a Host are automatically inherited by lower-level
- containers, unless explicitly overridden.</p>
+ <p>A Catalina container (<a href="engine.html">Engine</a>,
+ <a href="host.html">Host</a>, or <a href="context.html">Context</a>) may
+ contain no more than one Realm element (although if supported by the Realm
+ this one Realm may itself contain multiple nested Realms). In addition, the
+ Realm associated with an Engine or a Host is automatically inherited by
+ lower-level containers unless the lower level container explicitly defines its
+ own Realm. If no Realm is configured for the Engine, an instance of the
+ <a href="#Null_Realm_-_org.apache.catalina.realm.NullRealm">Null Realm</a>
+ will be configured for the Engine automatically.</p>
<p>For more in-depth information about container managed security in web
- applications, as well as more information on configuring and using the
- standard realm component implementations, please see the
+ applications, as well as more information on configuring and using the
+ standard realm component implementations, please see the
<a href="../realm-howto.html">Container-Managed Security Guide</a>.
</p>
- <blockquote><em>
- <p>The description below uses the variable name $CATALINA_BASE to refer the
+ <p><em>The description below uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
- not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE
+ not configured Tomcat for multiple instances by setting a CATALINA_BASE
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
- the directory into which you have installed Tomcat 6.</p>
- </em></blockquote>
+ the directory into which you have installed Tomcat.</em></p>
</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>
@@ -42,7 +119,7 @@
<p>All implementations of <strong>Realm</strong>
support the following attributes:</p>
- <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>className</code></strong></td><td align="left" valign="center">
+ <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">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Realm</code> interface.</p>
</td></tr></table>
@@ -57,7 +134,7 @@
<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>
- <p>The <strong>JDBC Database Realm</strong> connects Catalina to
+ <p>The <strong>JDBC Database Realm</strong> connects Tomcat to
a relational database, accessed through an appropriate JDBC driver,
to perform lookups of usernames, passwords, and their associated
roles. Because the lookup is done each time that it is required,
@@ -68,7 +145,7 @@
connection to the underlying database, as well as the table and
column names used to retrieve the required information:</p>
- <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>allRolesMode</code></td><td align="left" valign="center">
+ <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">
<p>This attribute controls how the special role name <code>*</code> is
handled when processing authorization constraints in web.xml. By
default, the specification compliant value of <code>strict</code> is
@@ -84,53 +161,62 @@
<strong>userRoleTable</strong> attributes become optional. If those two
attributes are omitted, the user's roles will not be loaded by this
Realm.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>connectionName</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionName</code></strong></td><td align="left" valign="center">
<p>The database username to use when establishing the JDBC
connection.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>connectionPassword</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionPassword</code></strong></td><td align="left" valign="center">
<p>The database password to use when establishing the JDBC
connection.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>connectionURL</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionURL</code></strong></td><td align="left" valign="center">
<p>The connection URL to be passed to the JDBC driver when
establishing a database connection.</p>
- </td></tr><tr><td align="left" valign="center"><code>digest</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
<p>The name of the <code>MessageDigest</code> algorithm used
to encode user passwords stored in the database. If not specified,
user passwords are assumed to be stored in clear-text.</p>
- </td></tr><tr><td align="left" valign="center"><code>digestEncoding</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">digestEncoding</code></td><td align="left" valign="center">
<p>The charset for encoding digests. If not specified, the platform
default will be used.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>driverName</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">driverName</code></strong></td><td align="left" valign="center">
<p>Fully qualified Java class name of the JDBC driver to be
used to connect to the authentication database.</p>
- </td></tr><tr><td align="left" valign="center"><code>roleNameCol</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleNameCol</code></td><td align="left" valign="center">
<p>Name of the column, in the "user roles" table, which contains
a role name assigned to the corresponding user.</p>
<p>This attribute is <strong>required</strong> in majority of
configurations. See <strong>allRolesMode</strong> attribute for
a rare case when it can be omitted.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>userCredCol</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
+ <p>The HTTP status code to use when the container needs to issue an HTTP
+ redirect to meet the requirements of a configured transport
+ guarantee. The provided status code is not validated. If not
+ specified, the default value of <code>302</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userCredCol</code></strong></td><td align="left" valign="center">
<p>Name of the column, in the "users" table, which contains
- the user's credentials (i.e. password(. If a value for the
+ the user's credentials (i.e. password). If a value for the
<code>digest</code> attribute is specified, this component
will assume that the passwords have been encoded with the
specified algorithm. Otherwise, they will be assumed to be
in clear text.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>userNameCol</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userNameCol</code></strong></td><td align="left" valign="center">
<p>Name of the column, in the "users" and "user roles" table,
that contains the user's username.</p>
- </td></tr><tr><td align="left" valign="center"><code>userRoleTable</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleTable</code></td><td align="left" valign="center">
<p>Name of the "user roles" table, which must contain columns
named by the <code>userNameCol</code> and <code>roleNameCol</code>
attributes.</p>
<p>This attribute is <strong>required</strong> in majority of
configurations. See <strong>allRolesMode</strong> attribute for
a rare case when it can be omitted.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>userTable</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userTable</code></strong></td><td align="left" valign="center">
<p>Name of the "users" table, which must contain columns named
by the <code>userNameCol</code> and <code>userCredCol</code>
attributes.</p>
- </td></tr><tr><td align="left" valign="center"><code>X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
<p>When using X509 client certificates, this specifies the class name
that will be used to retrieve the user name from the certificate.
The class must implement the
@@ -148,7 +234,7 @@
<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>
- <p>The <strong>DataSource Database Realm</strong> connects Catalina to
+ <p>The <strong>DataSource Database Realm</strong> connects Tomcat to
a relational database, accessed through a JNDI named JDBC DataSource
to perform lookups of usernames, passwords, and their associated
roles. Because the lookup is done each time that it is required,
@@ -168,7 +254,7 @@
of the JNDI JDBC DataSource, as well as the table and
column names used to retrieve the required information:</p>
- <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>allRolesMode</code></td><td align="left" valign="center">
+ <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">
<p>This attribute controls how the special role name <code>*</code> is
handled when processing authorization constraints in web.xml. By
default, the specification compliant value of <code>strict</code> is
@@ -184,45 +270,54 @@
<strong>userRoleTable</strong> attributes become optional. If those two
attributes are omitted, the user's roles will not be loaded by this
Realm.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>dataSourceName</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">dataSourceName</code></strong></td><td align="left" valign="center">
<p>The name of the JNDI JDBC DataSource for this Realm.</p>
- </td></tr><tr><td align="left" valign="center"><code>digest</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
<p>The name of the <code>MessageDigest</code> algorithm used
to encode user passwords stored in the database. If not specified,
user passwords are assumed to be stored in clear-text.</p>
- </td></tr><tr><td align="left" valign="center"><code>localDataSource</code></td><td align="left" valign="center">
- <p>When the realm is nested inside a Context element, this allows the
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">localDataSource</code></td><td align="left" valign="center">
+ <p>When the realm is nested inside a Context element, this allows the
realm to use a DataSource defined for the Context rather than a global
- DataSource. If not specified, the default is <code>false</code>: use a
+ DataSource. If not specified, the default is <code>false</code>: use a
global DataSource.</p>
- </td></tr><tr><td align="left" valign="center"><code>roleNameCol</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleNameCol</code></td><td align="left" valign="center">
<p>Name of the column, in the "user roles" table, which contains
a role name assigned to the corresponding user.</p>
<p>This attribute is <strong>required</strong> in majority of
configurations. See <strong>allRolesMode</strong> attribute for
a rare case when it can be omitted.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>userCredCol</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
+ <p>The HTTP status code to use when the container needs to issue an HTTP
+ redirect to meet the requirements of a configured transport
+ guarantee. The provided status code is not validated. If not
+ specified, the default value of <code>302</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userCredCol</code></strong></td><td align="left" valign="center">
<p>Name of the column, in the "users" table, which contains
- the user's credentials (i.e. password(. If a value for the
+ the user's credentials (i.e. password). If a value for the
<code>digest</code> attribute is specified, this component
will assume that the passwords have been encoded with the
specified algorithm. Otherwise, they will be assumed to be
in clear text.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>userNameCol</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userNameCol</code></strong></td><td align="left" valign="center">
<p>Name of the column, in the "users" and "user roles" table,
that contains the user's username.</p>
- </td></tr><tr><td align="left" valign="center"><code>userRoleTable</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleTable</code></td><td align="left" valign="center">
<p>Name of the "user roles" table, which must contain columns
named by the <code>userNameCol</code> and <code>roleNameCol</code>
attributes.</p>
<p>This attribute is <strong>required</strong> in majority of
configurations. See <strong>allRolesMode</strong> attribute for
a rare case when it can be omitted.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>userTable</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userTable</code></strong></td><td align="left" valign="center">
<p>Name of the "users" table, which must contain columns named
by the <code>userNameCol</code> and <code>userCredCol</code>
attributes.</p>
- </td></tr><tr><td align="left" valign="center"><code>X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
<p>When using X509 client certificates, this specifies the class name
that will be used to retrieve the user name from the certificate.
The class must implement the
@@ -240,7 +335,7 @@
<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>
- <p>The <strong>JNDI Directory Realm</strong> connects Catalina to
+ <p>The <strong>JNDI Directory Realm</strong> connects Tomcat to
an LDAP Directory, accessed through an appropriate JNDI driver,
that stores usernames, passwords, and their associated
roles. Changes to the directory are immediately reflected in the
@@ -274,14 +369,14 @@
directory and the element and attribute names used to retrieve
information from the directory:</p>
- <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>adCompat</code></td><td align="left" valign="center">
+ <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">
<p>Microsoft Active Directory often returns referrals.
When iterating over NamingEnumerations these lead to
PartialResultExceptions. If you want us to ignore those exceptions,
set this attribute to "true". Unfortunately there's no stable way
to detect, if the Exceptions really come from an AD referral.
The default value is "false".</p>
- </td></tr><tr><td align="left" valign="center"><code>allRolesMode</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
<p>This attribute controls how the special role name <code>*</code> is
handled when processing authorization constraints in web.xml. By
default, the specification compliant value of <code>strict</code> is
@@ -292,56 +387,68 @@
authenticated and no check will be made for assigned roles unless roles
are defined in web.xml in which case the user must be assigned at least
one of those roles.</p>
- </td></tr><tr><td align="left" valign="center"><code>alternateURL</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">alternateURL</code></td><td align="left" valign="center">
<p>If a socket connection can not be made to the provider at
the <code>connectionURL</code> an attempt will be made to use the
<code>alternateURL</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>authentication</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">authentication</code></td><td align="left" valign="center">
<p>A string specifying the type of authentication to use.
"none", "simple", "strong" or a provider specific definition
can be used. If no value is given the providers default is used.</p>
- </td></tr><tr><td align="left" valign="center"><code>commonRole</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cipherSuites</code></td><td align="left" valign="center">
+ <p>Specify which cipher suites are allowed when trying to open
+ a secured connection using StartTLS. The allowed cipher suites
+ are specified by a comma separated list. The default is to use the
+ cipher suites of the JVM.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">commonRole</code></td><td align="left" valign="center">
<p>A role name assigned to each successfully authenticated user in
addition to the roles retrieved from LDAP. If not specified, only
the roles retrieved via LDAP are used.</p>
- </td></tr><tr><td align="left" valign="center"><code>connectionName</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionName</code></td><td align="left" valign="center">
<p>The directory username to use when establishing a
connection to the directory for LDAP search operations. If not
specified an anonymous connection is made, which is often
sufficient unless you specify the <code>userPassword</code>
property.</p>
- </td></tr><tr><td align="left" valign="center"><code>connectionPassword</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionPassword</code></td><td align="left" valign="center">
<p>The directory password to use when establishing a
connection to the directory for LDAP search operations. If not
specified an anonymous connection is made, which is often
sufficient unless you specify the <code>userPassword</code>
property.</p>
- </td></tr><tr><td align="left" valign="center"><code>connectionTimeout</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionTimeout</code></td><td align="left" valign="center">
<p>The timeout in milliseconds to use when establishing the connection
to the LDAP directory. If not specified, a value of 5000 (5 seconds) is
used.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>connectionURL</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionURL</code></strong></td><td align="left" valign="center">
<p>The connection URL to be passed to the JNDI driver when
establishing a connection to the directory.</p>
- </td></tr><tr><td align="left" valign="center"><code>contextFactory</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">contextFactory</code></td><td align="left" valign="center">
<p>Fully qualified Java class name of the factory class used
to acquire our JNDI <code>InitialContext</code>. By default,
assumes that the standard JNDI LDAP provider will be utilized.</p>
- </td></tr><tr><td align="left" valign="center"><code>derefAliases</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">derefAliases</code></td><td align="left" valign="center">
<p>A string specifying how aliases are to be dereferenced during
search operations. The allowed values are "always", "never",
"finding" and "searching". If not specified, "always" is used.</p>
- </td></tr><tr><td align="left" valign="center"><code>digest</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
<p>The digest algorithm to apply to the plaintext password offered
by the user before comparing it with the value retrieved from the
directory. Valid values are those accepted for the algorithm name
by the <code>java.security.MessageDigest</code> class. If not
specified the plaintext password is assumed to be retrieved. Not
required unless <code>userPassword</code> is specified</p>
- </td></tr><tr><td align="left" valign="center"><code>protocol</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">hostnameVerifierClassName</code></td><td align="left" valign="center">
+ <p>The name of the class to use for hostname verification when
+ using StartTLS for securing the connection to the ldap server.
+ The default constructor will be used to construct an instance of
+ the verifier class. The default is to accept only those hostnames,
+ that are valid according to the peer certificate of the ldap
+ server.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">protocol</code></td><td align="left" valign="center">
<p>A string specifying the security protocol to use. If not given
the providers default is used.</p>
- </td></tr><tr><td align="left" valign="center"><code>referrals</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">referrals</code></td><td align="left" valign="center">
<p>How do we handle JNDI referrals? Allowed values are
"ignore", "follow", or "throw" (see javax.naming.Context.REFERRAL
for more information).
@@ -349,37 +456,116 @@
If you need to follow them set referrals to "follow".
Caution: if your DNS is not part of AD, the LDAP client lib might try
to resolve your domain name in DNS to find another LDAP server.</p>
- </td></tr><tr><td align="left" valign="center"><code>roleBase</code></td><td align="left" valign="center">
- <p>The base directory entry for performing role searches. If
- not specified the top-level element in the directory context
- will be used.</p>
- </td></tr><tr><td align="left" valign="center"><code>roleName</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleBase</code></td><td align="left" valign="center">
+ <p>The base directory entry for performing role searches. If not
+ specified the top-level element in the directory context will be used.
+ If specified it may optionally include pattern replacements
+ "{0}".."{n}" corresponding to the name parts of the
+ user's distinguished name (as returned by
+ <code>javax.naming.Name.get()</code>).</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleName</code></td><td align="left" valign="center">
<p>The name of the attribute that contains role names in the
directory entries found by a role search. In addition you can
use the <code>userRoleName</code> property to specify the name
of an attribute, in the user's entry, containing additional
- role names. If <code>roleName</code> is not specified a role
+ role names.</p>
+ <p>If <code>roleName</code> is not specified a role
search does not take place, and roles are taken only from the
user's entry.</p>
- </td></tr><tr><td align="left" valign="center"><code>roleSearch</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleNested</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> if you want to nest roles into roles.
+ When a role search is performed and the value of this property is
+ <code>true</code>, the search will be repeated recursively to find
+ all the roles that belong to the user either directly or indirectly.
+ If not specified, the default value of <code>false</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSearch</code></td><td align="left" valign="center">
<p>The LDAP filter expression used for performing role
- searches. Use <code>{0}</code> to substitute the
- distinguished name (DN) of the user, and/or <code>{1}</code> to
- substitute the username. If not specified a role search does
- not take place and roles are taken only from the attribute in
- the user's entry specified by the <code>userRoleName</code>
- property.</p>
- </td></tr><tr><td align="left" valign="center"><code>roleSubtree</code></td><td align="left" valign="center">
+ searches.</p>
+
+ <p>Use <code>{0}</code> to substitute the distinguished name (DN)
+ of the user, and/or <code>{1}</code> to substitute the username,
+ and/or <code>{2}</code> for the value of an attribute from the
+ user's directory entry, of the authenticated user.
+ The name of the attribute that provides the value for <code>{2}</code>
+ is configured by the <code>userRoleAttribute</code> property.</p>
+
+ <p>When <code>roleNested</code> property is <code>true</code>,
+ this filter expression will be also used to recursively search for
+ other roles, which indirectly belong to this user. To find the
+ roles that match the newly found role, the following values
+ are used:
+ <code>{0}</code> is substituted by the distinguished name of the newly
+ found role, and both <code>{1}</code> and <code>{2}</code> are
+ substituted by the name of the role (see the <code>roleName</code>
+ property). The <code>userRoleAttribute</code> property is not
+ applicable to this search.</p>
+
+ <p>If this property is not specified, a role search does not take
+ place and roles are taken only from the attribute in the user's entry
+ specified by the <code>userRoleName</code> property.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSearchAsUser</code></td><td align="left" valign="center">
+ <p> When searching for user roles, should the search be performed as the
+ user currently being authenticated? If false,
+ <code>connectionName</code> and <code>connectionPassword</code> will be
+ used if specified, else an anonymous. If not specified, the default
+ value of <code>false</code> is used. Note that when accessing the
+ directory using delegated credentials, this attribute is always ignored
+ and the search is performed using the delegated credentials.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSubtree</code></td><td align="left" valign="center">
<p>Set to <code>true</code> if you want to search the entire
subtree of the element specified by the <code>roleBase</code>
property for role entries associated with the user. The
default value of <code>false</code> causes only the top level
to be searched.</p>
- </td></tr><tr><td align="left" valign="center"><code>userBase</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">sizeLimit</code></td><td align="left" valign="center">
+ <p>Specifies the maximum number of records to return when using the
+ <code>userSearch</code> attribute. If not specified, the default of
+ <code>0</code> is used which indicates no limit.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">spnegoDelegationQop</code></td><td align="left" valign="center">
+ <p>When the JNDI Realm is used with the SPNEGO authenticator and
+ <code>useDelegatedCredential</code> is <code>true</code> this attribute
+ controls the QOP (Quality of Protection) that should be used for
+ the connection to the LDAP
+ server after authentication. This value is used to set the
+ <code>javax.security.sasl.qop</code> environment property for the LDAP
+ connection. This attribute should be a comma-separated list of values
+ selected from <code>auth-conf</code>, <code>auth-int</code> and
+ <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>
+ <p>The default value is <code>auth-conf</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">sslProtocol</code></td><td align="left" valign="center">
+ <p>Specifies which ssl protocol should be used, when connecting with
+ StartTLS. The default is to let the jre decide. If you need even more
+ control, you can specify the <code>SSLSocketFactory</code> to use.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">sslSocketFactory</code></td><td align="left" valign="center">
+ <p>Specifies which <code>SSLSocketFactory</code> to use when connecting
+ to the ldap server using StartTLS. An instance of the class will be
+ constructed using the default constructor. If none class name is given
+ the default jre <code>SSLSocketFactory</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">timeLimit</code></td><td align="left" valign="center">
+ <p>Specifies the time (in milliseconds) to wait for records to be
+ returned when using the <code>userSearch</code> attribute. If not
+ specified, the default of <code>0</code> is used which indicates no
+ limit.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
+ <p>The HTTP status code to use when the container needs to issue an HTTP
+ redirect to meet the requirements of a configured transport
+ guarantee. The provided status code is not validated. If not
+ specified, the default value of <code>302</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">useDelegatedCredential</code></td><td align="left" valign="center">
+ <p>When the JNDIRealm is used with the SPNEGO authenticator, delegated
+ credentials for the user may be available. If such credentials are
+ present, this attribute controls whether or not they are used to
+ connect to the directory. If not specified, the default value of
+ <code>true</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userBase</code></td><td align="left" valign="center">
<p>The base element for user searches performed using the
<code>userSearch</code> expression. Not used if you are using
the <code>userPattern</code> expression.</p>
- </td></tr><tr><td align="left" valign="center"><code>userPassword</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userPassword</code></td><td align="left" valign="center">
<p>Name of the attribute in the user's entry containing the
user's password. If you specify this value, JNDIRealm will
bind to the directory using the values specified by
@@ -392,14 +578,18 @@
user's entry and the password presented by the user, with a
successful bind being interpreted as an authenticated
user.</p>
- </td></tr><tr><td align="left" valign="center"><code>userPattern</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userPattern</code></td><td align="left" valign="center">
<p>Pattern for the distinguished name (DN) of the user's
directory entry, with <code>{0}</code> marking where the
actual username should be inserted. You can use this property
instead of <code>userSearch</code>, <code>userSubtree</code>
and <code>userBase</code> when the distinguished name contains
- the username and is otherwise the same for all users.</p>
- </td></tr><tr><td align="left" valign="center"><code>userRoleName</code></td><td align="left" valign="center">
+ the username and is otherwise the same for all users. Note that
+ when accessing the directory using delegated credentials, this
+ attribute is always ignored and <code>userSearch</code>,
+ <code>userSubtree</code> and <code>userBase</code> are always
+ used instead.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleName</code></td><td align="left" valign="center">
<p>The name of an attribute in the user's directory entry
containing zero or more values for the names of roles assigned
to this user. In addition you can use the
@@ -408,7 +598,15 @@
by searching the directory. If <code>userRoleName</code> is
not specified all the roles for a user derive from the role
search.</p>
- </td></tr><tr><td align="left" valign="center"><code>userSearch</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleAttribute</code></td><td align="left" valign="center">
+ <p>The name of an attribute in the user's directory entry
+ containing the value that you wish to use when you search for
+ roles. This is especially useful for RFC 2307 where
+ the role memberUid can be the <code>uid</code> or the
+ <code>uidNumber</code> of the user. This value will be
+ marked as <code>{2}</code> in your role search filter expression.
+ This value will NOT be available for nested role searches.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userSearch</code></td><td align="left" valign="center">
<p>The LDAP filter expression to use when searching for a
user's directory entry, with <code>{0}</code> marking where
the actual username should be inserted. Use this property
@@ -416,14 +614,26 @@
<code>userSubtree</code> properties) instead of
<code>userPattern</code> to search the directory for the
user's entry.</p>
- </td></tr><tr><td align="left" valign="center"><code>userSubtree</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userSearchAsUser</code></td><td align="left" valign="center">
+ <p> When searching for a user's entry, should the search be performed as
+ the user currently being authenticated? If false,
+ <code>connectionName</code> and <code>connectionPassword</code> will be
+ used if specified, else an anonymous. If not specified, the default
+ value of <code>false</code> is used. Note that when accessing the
+ directory using delegated credentials, this attribute is always ignored
+ and the search is performed using the delegated credentials.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userSubtree</code></td><td align="left" valign="center">
<p>Set to <code>true</code> if you want to search the entire
subtree of the element specified by the <code>userBase</code>
property for the user's entry. The default value of
<code>false</code> causes only the top level to be searched.
Not used if you are using the <code>userPattern</code>
expression.</p>
- </td></tr><tr><td align="left" valign="center"><code>X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">useStartTls</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> if you want to use StartTLS for securing
+ the connection to the ldap server. The default value is <code>false</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
<p>When using X509 client certificates, this specifies the class name
that will be used to retrieve the user name from the certificate.
The class must implement the
@@ -448,7 +658,7 @@
<p>The UserDatabase Realm implementation supports the following
additional attributes:</p>
- <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>allRolesMode</code></td><td align="left" valign="center">
+ <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">
<p>This attribute controls how the special role name <code>*</code> is
handled when processing authorization constraints in web.xml. By
default, the specification compliant value of <code>strict</code> is
@@ -459,10 +669,15 @@
authenticated and no check will be made for assigned roles unless roles
are defined in web.xml in which case the user must be assigned at least
one of those roles.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>resourceName</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">resourceName</code></strong></td><td align="left" valign="center">
<p>The name of the global <code>UserDatabase</code> resource
that this realm will use for user, password and role information.</p>
- </td></tr><tr><td align="left" valign="center"><code>X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
+ <p>The HTTP status code to use when the container needs to issue an HTTP
+ redirect to meet the requirements of a configured transport
+ guarantee. The provided status code is not validated. If not
+ specified, the default value of <code>302</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
<p>When using X509 client certificates, this specifies the class name
that will be used to retrieve the user name from the certificate.
The class must implement the
@@ -494,7 +709,7 @@
<p>The Memory Based Realm implementation supports the following
additional attributes:</p>
- <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>allRolesMode</code></td><td align="left" valign="center">
+ <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">
<p>This attribute controls how the special role name <code>*</code> is
handled when processing authorization constraints in web.xml. By
default, the specification compliant value of <code>strict</code> is
@@ -505,17 +720,26 @@
authenticated and no check will be made for assigned roles unless roles
are defined in web.xml in which case the user must be assigned at least
one of those roles.</p>
- </td></tr><tr><td align="left" valign="center"><code>digest</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
<p>The digest algorithm used to store passwords in non-plaintext
formats. Valid values are those accepted for the algorithm name by the
<code>java.security.MessageDigest</code> class. If not specified,
passwords are stored in clear text.</p>
- </td></tr><tr><td align="left" valign="center"><code>pathname</code></td><td align="left" valign="center">
- <p>Absolute or relative (to $CATALINA_BASE) pathname to the XML file
- containing our user information. See below for details on the
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">pathname</code></td><td align="left" valign="center">
+ <p>URL, absolute path or relative path (to $CATALINA_BASE) for the XML
+ file containing our user information. See below for details on the
XML element format required. If no pathname is specified, the
default value is <code>conf/tomcat-users.xml</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
+ <p>The HTTP status code to use when the container needs to issue an HTTP
+ redirect to meet the requirements of a configured transport
+ guarantee. The provided status code is not validated. If not
+ specified, the default value of <code>302</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
<p>When using X509 client certificates, this specifies the class name
that will be used to retrieve the user name from the certificate.
The class must implement the
@@ -534,8 +758,10 @@
<li>Each <code><user></code> element must have the following
attributes:
<ul>
- <li><strong>name</strong> - Username of this user (must be unique
- within this file).</li>
+ <li><strong>username</strong> - Username of this user (must be unique
+ within this file).<br>
+ For compatibility, it is allowed to use <strong>name</strong> as an
+ alternative name for this attribute.</li>
<li><strong>password</strong> - Password of this user (in
clear text).</li>
<li><strong>roles</strong> - Comma-delimited list of the role names
@@ -552,7 +778,7 @@
<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>
- <p><strong>JAASRealm</strong> is an implementation of the Tomcat 6
+ <p><strong>JAASRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that authenticates users through the Java
Authentication & Authorization Service (JAAS) framework which is now
provided as part of the standard J2SE API.</p>
@@ -575,7 +801,7 @@
<p>The JAAS Realm implementation supports the following additional
attributes:</p>
- <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>allRolesMode</code></td><td align="left" valign="center">
+ <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">
<p>This attribute controls how the special role name <code>*</code> is
handled when processing authorization constraints in web.xml. By
default, the specification compliant value of <code>strict</code> is
@@ -586,24 +812,39 @@
authenticated and no check will be made for assigned roles unless roles
are defined in web.xml in which case the user must be assigned at least
one of those roles.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>appName</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">appName</code></strong></td><td align="left" valign="center">
<p>The name of the application as configured in your login configuration
- file
+ file
(<a href="http://docs.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS LoginConfig</a>).</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>userClassNames</code></strong></td><td align="left" valign="center">
- <p>A comma-separated list of the names of the classes that you have made
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userClassNames</code></strong></td><td align="left" valign="center">
+ <p>A comma-separated list of the names of the classes that you have made
for your user <code>Principals</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>roleClassNames</code></td><td align="left" valign="center">
- <p>A comma-separated list of the names of the classes that you have made
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">configFile</code></td><td align="left" valign="center">
+ <p>The name of a JAAS configuration file to use with this Realm. It will
+ be searched for using <code>ClassLoader#getResource(String)</code> so it
+ is possible for the configuration to be bundled within a web
+ application. If not specified, the default JVM global JAAS configuration
+ will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleClassNames</code></td><td align="left" valign="center">
+ <p>A comma-separated list of the names of the classes that you have made
for your role <code>Principals</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>useContextClassLoader</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
+ <p>The HTTP status code to use when the container needs to issue an HTTP
+ redirect to meet the requirements of a configured transport
+ guarantee. The provided status code is not validated. If not
+ specified, the default value of <code>302</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">useContextClassLoader</code></td><td align="left" valign="center">
<p>Instructs JAASRealm to use the context class loader for loading the
user-specified <code>LoginModule</code> class and associated
<code>Principal</code> classes. The default value is <code>true</code>,
which is backwards-compatible with the way Tomcat 5 works. To load
classes using the container's classloader, specify
<code>false</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
<p>When using X509 client certificates, this specifies the class name
that will be used to retrieve the user name from the certificate.
The class must implement the
@@ -621,7 +862,7 @@
<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>
- <p><strong>CombinedRealm</strong> is an implementation of the Tomcat 6
+ <p><strong>CombinedRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that authenticates users through one or more
sub-Realms.</p>
@@ -643,7 +884,7 @@
<p>The CombinedRealm implementation supports the following additional
attributes.</p>
- <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>allRolesMode</code></td><td align="left" valign="center">
+ <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">
<p>This attribute controls how the special role name <code>*</code> is
handled when processing authorization constraints in web.xml. By
default, the specification compliant value of <code>strict</code> is
@@ -654,20 +895,25 @@
authenticated and no check will be made for assigned roles unless roles
are defined in web.xml in which case the user must be assigned at least
one of those roles.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
+ <p>The HTTP status code to use when the container needs to issue an HTTP
+ redirect to meet the requirements of a configured transport
+ guarantee. The provided status code is not validated. If not
+ specified, the default value of <code>302</code> is used.</p>
</td></tr></table>
</blockquote></td></tr></table>
<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>
- <p><strong>LockOutRealm</strong> is an implementation of the Tomcat 6
+ <p><strong>LockOutRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that extends the CombinedRealm to provide lock
out functionality to provide a user lock out mechanism if there are too many
failed authentication attempts in a given period of time.</p>
-
+
<p>To ensure correct operation, there is a reasonable degree of
synchronization in this Realm.</p>
-
+
<p>This Realm does not require modification to the underlying Realms or the
associated user storage mechanisms. It achieves this by recording all failed
logins, including those for users that do not exist. To prevent a DOS by
@@ -684,7 +930,7 @@
<p>The LockOutRealm implementation supports the following additional
attributes.</p>
- <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>allRolesMode</code></td><td align="left" valign="center">
+ <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">
<p>This attribute controls how the special role name <code>*</code> is
handled when processing authorization constraints in web.xml. By
default, the specification compliant value of <code>strict</code> is
@@ -695,20 +941,29 @@
authenticated and no check will be made for assigned roles unless roles
are defined in web.xml in which case the user must be assigned at least
one of those roles.</p>
- </td></tr><tr><td align="left" valign="center"><code>cacheRemovalWarningTime</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cacheRemovalWarningTime</code></td><td align="left" valign="center">
<p>If a failed user is removed from the cache because the cache is too
big before it has been in the cache for at least this period of time (in
seconds) a warning message will be logged. Defaults to 3600 (1 hour).</p>
- </td></tr><tr><td align="left" valign="center"><code>cacheSize</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cacheSize</code></td><td align="left" valign="center">
<p>Number of users that have failed authentication to keep in cache. Over
time the cache will grow to this size and may not shrink. Defaults to
1000.</p>
- </td></tr><tr><td align="left" valign="center"><code>failureCount</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">failureCount</code></td><td align="left" valign="center">
<p>The number of times in a row a user has to fail authentication to be
locked out. Defaults to 5.</p>
- </td></tr><tr><td align="left" valign="center"><code>lockOutTime</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">lockOutTime</code></td><td align="left" valign="center">
<p>The time (in seconds) a user is locked out for after too many
- authentication failures. Defaults to 300 (5 minutes).</p>
+ authentication failures. Defaults to 300 (5 minutes). Further
+ authentication failures during the lock out time will cause the lock out
+ timer to reset to zero, effectively extending the lock out time. Valid
+ authentication attempts during the lock out period will not succeed but
+ will also not reset the lock out time.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">transportGuaranteeRedirectStatus</code></td><td align="left" valign="center">
+ <p>The HTTP status code to use when the container needs to issue an HTTP
+ redirect to meet the requirements of a configured transport
+ guarantee. The provided status code is not validated. If not
+ specified, the default value of <code>302</code> is used.</p>
</td></tr></table>
<p>See the <a href="../realm-howto.html">Container-Managed Security
@@ -717,6 +972,26 @@
</blockquote></td></tr></table>
+ <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>
+
+ <p><strong>NullRealm</strong> is a minimal implementation of the Tomcat
+ <code>Realm</code> interface that always returns null when an attempt is
+ made to validate a user name and associated credentials. It is intended to
+ be used as a default Realm implementation when no other Realm is
+ specified.</p>
+
+ <p>The NullRealm implementation supports the following additional
+ attributes.</p>
+
+ <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">
+ <p>The HTTP status code to use when the container needs to issue an HTTP
+ redirect to meet the requirements of a configured transport
+ guarantee. The provided status code is not validated. If not
+ specified, the default value of <code>302</code> is used.</p>
+ </td></tr></table>
+
+ </blockquote></td></tr></table>
+
</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>
<h3>CombinedRealm Implementation</h3>
@@ -726,7 +1001,7 @@
<strong><Realm></strong> elements may be nested inside it.</p>
<h3>Other Realm Implementations</h3>
-
+
<p>No other Realm implementation supports nested components.</p>
</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>
@@ -734,6 +1009,31 @@
<p>See <a href="host.html">Single Sign On</a> for information about
configuring Single Sign On support for a virtual host.</p>
-</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
- Copyright © 1999-2014, Apache Software Foundation
+</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
+ on improving documentation for Apache Tomcat.<br><br>
+ If you have trouble and need help, read
+ <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
+ and ask your question on the tomcat-users
+ <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
+ Do not ask such questions here. This is not a Q&A section.<br><br>
+ The Apache Comments System is explained <a href="../comments.html">here</a>.
+ Comments may be removed by our moderators if they are either
+ implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
+ var comments_shortname = 'tomcat';
+ var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/config/realm.html';
+ (function(w, d) {
+ if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
+ d.write('<div id="comments_thread"><\/div>');
+ var s = d.createElement('script');
+ s.type = 'text/javascript';
+ s.async = true;
+ s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
+ (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
+ }
+ else {
+ d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
+ }
+ })(window, document);
+ //--><!]]></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>
+ Copyright © 1999-2017, Apache Software Foundation
</em></font></div></td></tr></table></body></html>
\ No newline at end of file