升级Tomcat版本 apache-tomcat-7.0.77
diff --git a/tomcat-uid/webapps/docs/realm-howto.html b/tomcat-uid/webapps/docs/realm-howto.html
index 8667198..d80508f 100644
--- a/tomcat-uid/webapps/docs/realm-howto.html
+++ b/tomcat-uid/webapps/docs/realm-howto.html
@@ -1,9 +1,84 @@
-<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 (6.0.41) - Realm Configuration HOW-TO</title><meta name="author" content="Craig R. McClanahan"><meta name="author" content="Yoav Shapira"><meta name="author" content="Andrew R. Jaquith"><style type="text/css" media="print">
- .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 (7.0.77) - Realm Configuration HOW-TO</title><meta name="author" content="Craig R. McClanahan"><meta name="author" content="Yoav Shapira"><meta name="author" content="Andrew R. Jaquith"><style type="text/css" media="print">
+ .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="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Tomcat 6.0</h1><h2>Realm Configuration HOW-TO</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
+ " 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="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL/TLS</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">16) MBeans Descriptors</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Realm Configuration HOW-TO</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
<ul><li><a href="#Quick_Start">Quick Start</a></li><li><a href="#Overview">Overview</a><ol><li><a href="#What_is_a_Realm?">What is a Realm?</a></li><li><a href="#Configuring_a_Realm">Configuring a Realm</a></li></ol></li><li><a href="#Common_Features">Common Features</a><ol><li><a href="#Digested_Passwords">Digested Passwords</a></li><li><a href="#Example_Application">Example Application</a></li><li><a href="#Manager_Application">Manager Application</a></li><li><a href="#Realm_Logging">Realm Logging</a></li></ol></li><li><a href="#Standard_Realm_Implementations">Standard Realm Implementations</a><ol><li><a href="#JDBCRealm">JDBCRealm</a></li><li><a href="#DataSourceRealm">DataSourceRealm</a></li><li><a href="#JNDIRealm">JNDIRealm</a></li><li><a href="#UserDatabaseRealm">UserDatabaseRealm</a></li><li><a href="#MemoryRealm">MemoryRealm</a></li><li><a href="#JAASRealm">JAASRealm</a></li><li><a href="#CombinedRealm">CombinedRealm</a></li><li><a href="#LockOutRealm">LockOutRealm</a></li></ol></li></ul>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Quick Start"><!--()--></a><a name="Quick_Start"><strong>Quick Start</strong></a></font></td></tr><tr><td><blockquote>
@@ -21,7 +96,7 @@
Specification (Version 2.4)</a>, Section 12.</p>
<p>For information about utilizing the <em>Single Sign On</em> feature of
-Tomcat 6 (allowing a user to authenticate themselves once across the entire
+Tomcat (allowing a user to authenticate themselves once across the entire
set of web applications associated with a virtual host), see
<a href="config/host.html#Single Sign On">here</a>.</p>
@@ -45,10 +120,10 @@
defining the interface between a servlet container and the associated user
and role information. In many cases, however, it is desirable to "connect"
a servlet container to some existing authentication database or mechanism
-that already exists in the production environment. Therefore, Tomcat 6
+that already exists in the production environment. Therefore, Tomcat
defines a Java interface (<code>org.apache.catalina.Realm</code>) that
can be implemented by "plug in" components to establish this connection.
-Five standard plug-ins are provided, supporting connections to various
+Six standard plug-ins are provided, supporting connections to various
sources of authentication information:</p>
<ul>
<li><a href="#JDBCRealm">JDBCRealm</a> - Accesses authentication information
@@ -71,12 +146,12 @@
</ul>
<p>It is also possible to write your own <code>Realm</code> implementation,
-and integrate it with Tomcat 6. To do so, you need to:
+and integrate it with Tomcat. To do so, you need to:
<ul>
<li>Implement <code>org.apache.catalina.Realm</code>,</li>
<li>Place your compiled realm in $CATALINA_HOME/lib,</li>
<li>Declare your realm as described in the "Configuring a Realm" section below,</li>
- <li>Declare your realm to the <a href="mbeans-descriptor-howto.html">MBeans Descriptor</a>.</li>
+ <li>Declare your realm to the <a href="mbeans-descriptors-howto.html">MBeans Descriptors</a>.</li>
</ul>
</p>
@@ -90,12 +165,12 @@
general, you will be adding an XML element to your <code>conf/server.xml</code>
configuration file, that looks something like this:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
<Realm className="... class name for this implementation"
... other attributes for this implementation .../>
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
-<p>The <code><Realm></code> element can be nested inside any one of
+<p>The <code><Realm></code> element can be nested inside any one of
of the following <code>Container</code> elements. The location of the
Realm element has a direct impact on the "scope" of that Realm
(i.e. which web applications will share the same authentication information):
@@ -160,10 +235,8 @@
method will return the digested password.</li>
<li>If you want to execute a command line utility to calculate the digested
password, simply execute
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-java org.apache.catalina.realm.RealmBase \
- -a {algorithm} {cleartext-password}
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+<div class="codeBox"><pre><code>CATALINA_HOME/bin/digest.[bat|sh] -a {algorithm} {cleartext-password}
+</code></pre></div>
and the digested version of this cleartext password will be returned to
standard output.</li>
</ul>
@@ -179,16 +252,9 @@
not specified in web.xml, the default value of <code>Authentication
required</code> is used.</p>
-<p>To use either of the above techniques, the
-<code>$CATALINA_HOME/lib/catalina.jar</code> and
-<code>$CATALINA_HOME/bin/tomcat-juli.jar</code> files will need to be
-on your class path to make the <code>RealmBase</code> class available.
-</p>
-
<p>Non-ASCII usernames and/or passwords are supported using
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>java org.apache.catalina.realm.RealmBase \
- -a {algorithm} -e {encoding} {input}
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+<div class="codeBox"><pre><code>CATALINA_HOME/bin/digest.[bat|sh] -a {algorithm} -e {encoding} {input}
+</code></pre></div>
but care is required to ensure that the non-ASCII input is
correctly passed to the digester.
The digester returns <code>{input}:{digest}</code>. If the input appears
@@ -200,7 +266,7 @@
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Example Application"><!--()--></a><a name="Example_Application"><strong>Example Application</strong></a></font></td></tr><tr><td><blockquote>
-<p>The example application shipped with Tomcat 6 includes an area that is
+<p>The example application shipped with Tomcat includes an area that is
protected by a security constraint, utilizing form-based login. To access it,
point your browser at
<a href="http://localhost:8080/examples/jsp/security/protected/">http://localhost:8080/examples/jsp/security/protected/</a>
@@ -243,7 +309,7 @@
<h3>Introduction</h3>
-<p><strong>JDBCRealm</strong> is an implementation of the Tomcat 6
+<p><strong>JDBCRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that looks up users in a relational database
accessed via a JDBC driver. There is substantial configuration flexibility
that lets you adapt to existing table and column names, as long as your
@@ -287,7 +353,7 @@
Note that <strong>only</strong> JAR files are recognized!</li>
<li>Set up a <code><Realm></code> element, as described below, in your
<code>$CATALINA_BASE/conf/server.xml</code> file.</li>
-<li>Restart Tomcat 6 if it is already running.</li>
+<li>Restart Tomcat if it is already running.</li>
</ol>
<h3>Realm Element Attributes</h3>
@@ -302,7 +368,7 @@
<p>An example SQL script to create the needed tables might look something
like this (adapt the syntax as required for your particular database):</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
create table users (
user_name varchar(15) not null primary key,
user_pass varchar(15) not null
@@ -313,26 +379,26 @@
role_name varchar(15) not null,
primary key (user_name, role_name)
);
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<p>Example <code>Realm</code> elements are included (commented out) in the
default <code>$CATALINA_BASE/conf/server.xml</code> file. Here's an example
for using a MySQL database called "authority", configured with the tables
described above, and accessed with username "dbuser" and password "dbpass":</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
<Realm className="org.apache.catalina.realm.JDBCRealm"
driverName="org.gjt.mm.mysql.Driver"
connectionURL="jdbc:mysql://localhost/authority?user=dbuser&amp;password=dbpass"
userTable="users" userNameCol="user_name" userCredCol="user_pass"
userRoleTable="user_roles" roleNameCol="role_name"/>
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<h3>Additional Notes</h3>
<p>JDBCRealm operates according to the following rules:</p>
<ul>
<li>When a user attempts to access a protected resource for the first time,
- Tomcat 6 will call the <code>authenticate()</code> method of this
+ Tomcat will call the <code>authenticate()</code> method of this
<code>Realm</code>. Thus, any changes you have made to the database
directly (new users, changed passwords or roles, etc.) will be immediately
reflected.</li>
@@ -356,7 +422,7 @@
<h3>Introduction</h3>
-<p><strong>DataSourceRealm</strong> is an implementation of the Tomcat 6
+<p><strong>DataSourceRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that looks up users in a relational database
accessed via a JNDI named JDBC DataSource. There is substantial configuration
flexibility that lets you adapt to existing table and column names, as long
@@ -372,7 +438,7 @@
<li>Password to be recognized by Tomcat when the user logs in.
This value may in cleartext or digested - see below for more
information.</li>
- </ul></li>
+ </ul></li>
<li>There must be a table, referenced below as the <em>user roles</em> table,
that contains one row for every valid role that is assigned to a
particular user. It is legal for a user to have zero, one, or more than
@@ -387,20 +453,23 @@
</ul>
<h3>Quick Start</h3>
-
+
<p>To set up Tomcat to use DataSourceRealm, you will need to follow these steps:</p>
-<ol>
+<ol>
<li>If you have not yet done so, create tables and columns in your database
that conform to the requirements described above.</li>
<li>Configure a database username and password for use by Tomcat, that has
at least read only access to the tables described above. (Tomcat will
never attempt to write to these tables.)</li>
<li>Configure a JNDI named JDBC DataSource for your database. Refer to the
- <a href="jndi-datasource-examples-howto.html">JNDI DataSource Example HOW-TO</a>
- for information on how to configure a JNDI named JDBC DataSource.</li>
+ <a href="jndi-datasource-examples-howto.html">JNDI DataSource Example
+ HOW-TO</a> for information on how to configure a JNDI named JDBC DataSource.
+ Be sure to set the <code>Realm</code>'s <code>localDataSource</code>
+ attribute appropriately, depending on where the JNDI DataSource is
+ defined.</li>
<li>Set up a <code><Realm></code> element, as described below, in your
<code>$CATALINA_BASE/conf/server.xml</code> file.</li>
-<li>Restart Tomcat 6 if it is already running.</li>
+<li>Restart Tomcat if it is already running.</li>
</ol>
<h3>Realm Element Attributes</h3>
@@ -415,7 +484,7 @@
<p>An example SQL script to create the needed tables might look something
like this (adapt the syntax as required for your particular database):</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
create table users (
user_name varchar(15) not null primary key,
user_pass varchar(15) not null
@@ -426,24 +495,24 @@
role_name varchar(15) not null,
primary key (user_name, role_name)
);
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<p>Here is an example for using a MySQL database called "authority", configured
with the tables described above, and accessed with the JNDI JDBC DataSource with
name "java:/comp/env/jdbc/authority".</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
<Realm className="org.apache.catalina.realm.DataSourceRealm"
dataSourceName="jdbc/authority"
userTable="users" userNameCol="user_name" userCredCol="user_pass"
userRoleTable="user_roles" roleNameCol="role_name"/>
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<h3>Additional Notes</h3>
<p>DataSourceRealm operates according to the following rules:</p>
<ul>
<li>When a user attempts to access a protected resource for the first time,
- Tomcat 6 will call the <code>authenticate()</code> method of this
+ Tomcat will call the <code>authenticate()</code> method of this
<code>Realm</code>. Thus, any changes you have made to the database
directly (new users, changed passwords or roles, etc.) will be immediately
reflected.</li>
@@ -467,7 +536,7 @@
<h3>Introduction</h3>
-<p><strong>JNDIRealm</strong> is an implementation of the Tomcat 6
+<p><strong>JNDIRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that looks up users in an LDAP directory
server accessed by a JNDI provider (typically, the standard LDAP
provider that is available with the JNDI API classes). The realm
@@ -611,13 +680,15 @@
<li><strong>roleSearch</strong> - the LDAP search filter for
selecting role entries. It optionally includes pattern
replacements "{0}" for the distinguished name and/or "{1}" for the
- username of the authenticated user.</li>
+ username and/or "{2}" for an attribute from user's directory entry,
+ of the authenticated user. Use <strong>userRoleAttribute</strong> to
+ specify the name of the attribute that provides the value for "{2}".</li>
<li><strong>roleName</strong> - the attribute in a role entry
containing the name of that role.</li>
<li><strong>roleNested</strong> - enable nested roles. Set to
- <code>true</code> if you want to nest roles in roles. If configured
+ <code>true</code> if you want to nest roles in roles. If configured, then
every newly found roleName and distinguished
Name will be recursively tried for a new role search.
The default value is <code>false</code>.</li>
@@ -650,7 +721,7 @@
never attempt to modify this information.)</li>
<li>Set up a <code><Realm></code> element, as described below, in your
<code>$CATALINA_BASE/conf/server.xml</code> file.</li>
-<li>Restart Tomcat 6 if it is already running.</li>
+<li>Restart Tomcat if it is already running.</li>
</ol>
<h3>Realm Element Attributes</h3>
@@ -671,22 +742,23 @@
<a href="http://www.openldap.org">http://www.openldap.org</a>. Assume that
your <code>slapd.conf</code> file contains the following settings
(among others):</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
database ldbm
suffix dc="mycompany",dc="com"
rootdn "cn=Manager,dc=mycompany,dc=com"
rootpw secret
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<p>We will assume for <code>connectionURL</code> that the directory
-server runs on the same machine as Tomcat. See <a href="http://java.sun.com/products/jndi/docs.html">http://java.sun.com/products/jndi/docs.html</a>
+server runs on the same machine as Tomcat. See <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jndi/index.html">
+http://docs.oracle.com/javase/7/docs/technotes/guides/jndi/index.html</a>
for more information about configuring and using the JNDI LDAP
provider.</p>
<p>Next, assume that this directory server has been populated with elements
as shown below (in LDIF format):</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
# Define top-level entry
dn: dc=mycompany,dc=com
@@ -735,7 +807,7 @@
objectClass: groupOfUniqueNames
cn: role1
uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<p>An example <code>Realm</code> element for the OpenLDAP directory
server configured as described above might look like this, assuming
@@ -743,7 +815,7 @@
application and that an anonymous connection is sufficient to search
the directory and retrieve role information:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
<Realm className="org.apache.catalina.realm.JNDIRealm"
connectionURL="ldap://localhost:389"
userPattern="uid={0},ou=people,dc=mycompany,dc=com"
@@ -751,7 +823,7 @@
roleName="cn"
roleSearch="(uniqueMember={0})"
/>
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<p>With this configuration, the realm will determine the user's
distinguished name by substituting the username into the
@@ -769,7 +841,7 @@
use an attribute of the user's entry to hold roles. Now the entry for
Janet Jones might read as follows:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
dn: uid=jjones,ou=people,dc=mycompany,dc=com
objectClass: inetOrgPerson
uid: jjones
@@ -779,11 +851,11 @@
memberOf: role2
memberOf: role3
userPassword: janet
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<p> This realm configuration would satisfy the new requirements:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
<Realm className="org.apache.catalina.realm.JNDIRealm"
connectionURL="ldap://localhost:389"
userBase="ou=people,dc=mycompany,dc=com"
@@ -793,7 +865,7 @@
roleName="cn"
roleSearch="(uniqueMember={0})"
/>
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<p>Now when Janet Jones logs in as "j.jones@mycompany.com", the realm
searches the directory for a unique entry with that value as its mail
@@ -808,7 +880,7 @@
the password from the directory and making a local comparison in the
realm, you might use a realm configuration like this:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
<Realm className="org.apache.catalina.realm.JNDIRealm"
connectionName="cn=Manager,dc=mycompany,dc=com"
connectionPassword="secret"
@@ -819,7 +891,7 @@
roleName="cn"
roleSearch="(uniqueMember={0})"
/>
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<p>However, as discussed above, the default bind mode for
authentication is usually to be preferred.</p>
@@ -829,7 +901,7 @@
<p>JNDIRealm operates according to the following rules:</p>
<ul>
<li>When a user attempts to access a protected resource for the first time,
- Tomcat 6 will call the <code>authenticate()</code> method of this
+ Tomcat will call the <code>authenticate()</code> method of this
<code>Realm</code>. Thus, any changes you have made to the directory
(new users, changed passwords or roles, etc.) will be immediately
reflected.</li>
@@ -853,7 +925,7 @@
<h3>Introduction</h3>
-<p><strong>UserDatabaseRealm</strong> is an implementation of the Tomcat 6
+<p><strong>UserDatabaseRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that uses a JNDI resource to store user
information. By default, the JNDI resource is backed by an XML file. It is not
designed for large-scale production use. At startup time, the UserDatabaseRealm
@@ -878,17 +950,17 @@
<h3>Example</h3>
-<p>The default installation of Tomcat 6 is configured with a UserDatabaseRealm
+<p>The default installation of Tomcat is configured with a UserDatabaseRealm
nested inside the <code><Engine></code> element, so that it applies
to all virtual hosts and web applications. The default contents of the
<code>conf/tomcat-users.xml</code> file is:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
<tomcat-users>
<user name="tomcat" password="tomcat" roles="tomcat" />
<user name="role1" password="tomcat" roles="role1" />
<user name="both" password="tomcat" roles="tomcat,role1" />
</tomcat-users>
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
<h3>Additional Notes</h3>
@@ -900,7 +972,7 @@
restarted. Changes may be made via the UserDatabase resource. Tomcat
provides MBeans that may be accessed via JMX for this purpose.</li>
<li>When a user attempts to access a protected resource for the first time,
- Tomcat 6 will call the <code>authenticate()</code> method of this
+ Tomcat will call the <code>authenticate()</code> method of this
<code>Realm</code>.</li>
<li>Once a user has been authenticated, the user (and his or her associated
roles) are cached within Tomcat for the duration of the user's login.
@@ -919,7 +991,7 @@
<h3>Introduction</h3>
<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
-Tomcat 6 <code>Realm</code> interface. It is not designed for production use.
+Tomcat <code>Realm</code> interface. It is not designed for production use.
At startup time, MemoryRealm loads information about all users, and their
corresponding roles, from an XML document (by default, this document is loaded
from <code>$CATALINA_BASE/conf/tomcat-users.xml</code>). Changes to the data
@@ -958,7 +1030,7 @@
this file will <strong>not</strong> be recognized until Tomcat is
restarted.</li>
<li>When a user attempts to access a protected resource for the first time,
- Tomcat 6 will call the <code>authenticate()</code> method of this
+ Tomcat will call the <code>authenticate()</code> method of this
<code>Realm</code>.</li>
<li>Once a user has been authenticated, the user (and his or her associated
roles) are cached within Tomcat for the duration of the user's login.
@@ -980,9 +1052,9 @@
<h3>Introduction</h3>
<p><strong>JAASRealm</strong> is an implementation of the Tomcat
-6 <code>Realm</code> interface that authenticates users through the Java
+<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>
+provided as part of the standard Java SE API.</p>
<p>Using JAASRealm gives the developer the ability to combine
practically any conceivable security realm with Tomcat's CMA. </p>
<p>JAASRealm is prototype for Tomcat of the JAAS-based
@@ -1002,36 +1074,36 @@
you will need to follow these steps:</p>
<ol>
<li>Write your own LoginModule, User and Role classes based
-on JAAS (see
-<a href="http://docs.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnOnly.html">the
-JAAS Authentication Tutorial</a> and
-<a href="http://docs.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.html">the JAAS Login Module
-Developer's Guide</a>) to be managed by the JAAS Login
+on JAAS (see
+<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/jaas/tutorials/GeneralAcnOnly.html">
+the JAAS Authentication Tutorial</a> and
+<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASLMDevGuide.html">
+the JAAS Login Module Developer's Guide</a>) to be managed by the JAAS Login
Context (<code>javax.security.auth.login.LoginContext</code>)
When developing your LoginModule, note that JAASRealm's built-in <code>CallbackHandler</code>
only recognizes the <code>NameCallback</code> and <code>PasswordCallback</code> at present.
</li>
<li>Although not specified in JAAS, you should create
-seperate classes to distinguish between users and roles, extending <code>javax.security.Principal</code>,
+separate classes to distinguish between users and roles, extending <code>javax.security.Principal</code>,
so that Tomcat can tell which Principals returned from your login
module are users and which are roles (see <code>org.apache.catalina.realm.JAASRealm</code>).
Regardless, the first Principal returned is <em>always</em> treated as the user Principal.
</li>
<li>Place the compiled classes on Tomcat's classpath
</li>
- <li>Set up a login.config file for Java (see <a href="http://docs.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS
-LoginConfig file</a>) and tell Tomcat where to find it by specifying
+ <li>Set up a login.config file for Java (see <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/jaas/tutorials/LoginConfigFile.html">
+JAAS LoginConfig file</a>) and tell Tomcat where to find it by specifying
its location to the JVM, for instance by setting the environment
variable: <code>JAVA_OPTS=$JAVA_OPTS -Djava.security.auth.login.config==$CATALINA_BASE/conf/jaas.config</code></li>
<li>Configure your security-constraints in your web.xml for
the resources you want to protect</li>
<li>Configure the JAASRealm module in your server.xml </li>
- <li>Restart Tomcat 6 if it is already running.</li>
+ <li>Restart Tomcat if it is already running.</li>
</ol>
<h3>Realm Element Attributes</h3>
<p>To configure JAASRealm as for step 6 above, you create
-a <code><Realm></code> element and nest it in your
+a <code><Realm></code> element and nest it in your
<code>$CATALINA_BASE/conf/server.xml</code>
file within your <code><Engine></code> node. The attributes for the
JAASRealm are defined in the <a href="config/realm.html">Realm</a>
@@ -1041,33 +1113,33 @@
<p>Here is an example of how your server.xml snippet should look.</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
<Realm className="org.apache.catalina.realm.JAASRealm"
appName="MyFooRealm"
userClassNames="org.foobar.realm.FooUser"
- roleClassNames="org.foobar.realm.FooRole"/>
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ roleClassNames="org.foobar.realm.FooRole"/>
+</code></pre></div>
-<p>It is the responsibility of your login module to create and save User and
-Role objects representing Principals for the user
-(<code>javax.security.auth.Subject</code>). If your login module doesn't
-create a user object but also doesn't throw a login exception, then the
-Tomcat CMA will break and you will be left at the
-http://localhost:8080/myapp/j_security_check URI or at some other
+<p>It is the responsibility of your login module to create and save User and
+Role objects representing Principals for the user
+(<code>javax.security.auth.Subject</code>). If your login module doesn't
+create a user object but also doesn't throw a login exception, then the
+Tomcat CMA will break and you will be left at the
+http://localhost:8080/myapp/j_security_check URI or at some other
unspecified location.</p>
<p>The flexibility of the JAAS approach is two-fold: </p>
<ul>
<li>you can carry out whatever processing you require behind
the scenes in your own login module.</li>
- <li>you can plug in a completely different LoginModule by changing the configuration
+ <li>you can plug in a completely different LoginModule by changing the configuration
and restarting the server, without any code changes to your application.</li>
</ul>
<h3>Additional Notes</h3>
<ul>
<li>When a user attempts to access a protected resource for
- the first time, Tomcat 6 will call the <code>authenticate()</code>
+ the first time, Tomcat will call the <code>authenticate()</code>
method of this <code>Realm</code>. Thus, any changes you have made in
the security mechanism directly (new users, changed passwords or
roles, etc.) will be immediately reflected.</li>
@@ -1081,7 +1153,7 @@
<li>As with other <code>Realm</code> implementations, digested passwords
are supported if the <code><Realm></code> element in <code>server.xml</code>
contains a <code>digest</code> attribute; JAASRealm's <code>CallbackHandler</code>
- will digest the password prior to passing it back to the <code>LoginModule</code></li>
+ will digest the password prior to passing it back to the <code>LoginModule</code></li>
</ul>
</blockquote></td></tr></table>
@@ -1091,7 +1163,7 @@
<h3>Introduction</h3>
- <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>
@@ -1112,13 +1184,13 @@
file within your <code><Engine></code> or <code><Host></code>.
You can also nest inside a <code><Context></code> node in a
<code>context.xml</code> file.</p>
-
+
<h3>Example</h3>
<p>Here is an example of how your server.xml snippet should look to use a
UserDatabase Realm and a DataSource Realm.</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
<Realm className="org.apache.catalina.realm.CombinedRealm" >
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
resourceName="UserDatabase"/>
@@ -1127,7 +1199,7 @@
userTable="users" userNameCol="user_name" userCredCol="user_pass"
userRoleTable="user_roles" roleNameCol="role_name"/>
</Realm>
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
</blockquote></td></tr></table>
@@ -1135,14 +1207,14 @@
<h3>Introduction</h3>
- <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
synchronisation 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
@@ -1164,21 +1236,46 @@
<code>context.xml</code> file. The attributes for the
LockOutRealm are defined in the <a href="config/realm.html">Realm</a>
configuration documentation.</p>
-
+
<h3>Example</h3>
<p>Here is an example of how your server.xml snippet should look to add lock out
functionality to a UserDatabase Realm.</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<div class="codeBox"><pre><code>
<Realm className="org.apache.catalina.realm.LockOutRealm" >
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
resourceName="UserDatabase"/>
</Realm>
-</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</code></pre></div>
</blockquote></td></tr></table>
-</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/realm-howto.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