1285 lines
88 KiB
HTML
1285 lines
88 KiB
HTML
|
<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Realm Configuration HOW-TO</title><meta name="author" value="Craig R. McClanahan"><meta name="email" value="craigmcc@apache.org"><meta name="author" value="Yoav Shapira"><meta name="email" value="yoavs@apache.org"><meta name="author" value="Andrew R. Jaquith"><meta name="email" value="arjaquith@mindspring.com"></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><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></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="true"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://tomcat.apache.org/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</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="status.html">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"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>Apache Tomcat 6.0</h1><h2>Realm Configuration HOW-TO</h2></td><td align="right" valign="top" nowrap="true"><small><a href="printer/realm-howto.html"><img src="./images/printer.gif" border="0" alt="Printer Friendly Version"><br>print-friendly<br>version
|
||
|
|
</a></small></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
<a href="#Quick Start">Quick Start</a><br>
|
||
|
|
<blockquote>
|
||
|
|
<a href="#What is a Realm?">What is a Realm?</a><br>
|
||
|
|
<a href="#Configuring a Realm">Configuring a Realm</a><br>
|
||
|
|
</blockquote>
|
||
|
|
<a href="#Common Features">Common Features</a><br>
|
||
|
|
<blockquote>
|
||
|
|
<a href="#Digested Passwords">Digested Passwords</a><br>
|
||
|
|
<a href="#Example Application">Example Application</a><br>
|
||
|
|
<a href="#Manager Application">Manager Application</a><br>
|
||
|
|
<a href="#Realm Logging">Logging Within Realms</a><br>
|
||
|
|
</blockquote>
|
||
|
|
<a href="#Standard Realm Implementations">
|
||
|
|
Standard Realm Implementations</a><br>
|
||
|
|
<blockquote>
|
||
|
|
<a href="#JDBCRealm">JDBCRealm</a><br>
|
||
|
|
<a href="#DataSourceRealm">DataSourceRealm</a><br>
|
||
|
|
<a href="#JNDIRealm">JNDIRealm</a><br>
|
||
|
|
<a href="#MemoryRealm">MemoryRealm</a><br>
|
||
|
|
<a href="#JAASRealm">JAASRealm</a><br>
|
||
|
|
</blockquote>
|
||
|
|
</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="Quick Start"><strong>Quick Start</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>This document describes how to configure Tomcat to support <em>container
|
||
|
|
managed security</em>, by connecting to an existing "database" of usernames,
|
||
|
|
passwords, and user roles. You only need to care about this if you are using
|
||
|
|
a web application that includes one or more
|
||
|
|
<code><security-constraint></code> elements, and a
|
||
|
|
<code><login-config></code> element defining how users are required
|
||
|
|
to authenticate themselves. If you are not utilizing these features, you can
|
||
|
|
safely skip this document.</p>
|
||
|
|
|
||
|
|
<p>For fundamental background information about container managed security,
|
||
|
|
see the <a href="http://java.sun.com/products/servlet/download.html">Servlet
|
||
|
|
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
|
||
|
|
set of web applications associated with a virtual host), see
|
||
|
|
<a href="config/host.html#Single Sign On">here</a>.</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="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="What is a Realm?"><strong>What is a Realm?</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>A <strong>Realm</strong> is a "database" of usernames and passwords that
|
||
|
|
identify valid users of a web application (or set of web applications), plus
|
||
|
|
an enumeration of the list of <em>roles</em> associated with each valid user.
|
||
|
|
You can think of roles as similar to <em>groups</em> in Unix-like operating
|
||
|
|
systems, because access to specific web application resources is granted to
|
||
|
|
all users possessing a particular role (rather than enumerating the list of
|
||
|
|
associated usernames). A particular user can have any number of roles
|
||
|
|
associated with their username.</p>
|
||
|
|
|
||
|
|
<p>Although the Servlet Specification describes a portable mechanism for
|
||
|
|
applications to <em>declare</em> their security requirements (in the
|
||
|
|
<code>web.xml</code> deployment descriptor), there is no portable API
|
||
|
|
defining the interface between a servlet container and the associated user
|
||
|
|
and role information. In many cases, however, it is desireable to "connect"
|
||
|
|
a servlet container to some existing authentication database or mechanism
|
||
|
|
that already exists in the production environment. Therefore, Tomcat 6
|
||
|
|
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
|
||
|
|
sources of authentication information:</p>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#JDBCRealm">JDBCRealm</a> - Accesses authentication information
|
||
|
|
stored in a relational database, accessed via a JDBC driver.</li>
|
||
|
|
<li><a href="#DataSourceRealm">DataSourceRealm</a> - Accesses authentication
|
||
|
|
information stored in a relational database, accessed via a named JNDI
|
||
|
|
JDBC DataSource.</li>
|
||
|
|
<li><a href="#JNDIRealm">JNDIRealm</a> - Accesses authentication information
|
||
|
|
stored in an LDAP based directory server, accessed via a JNDI provider.
|
||
|
|
</li>
|
||
|
|
<li><a href="#MemoryRealm">MemoryRealm</a> - Accesses authentication
|
||
|
|
information stored in an in-memory object collection, which is initialized
|
||
|
|
from an XML document (<code>conf/tomcat-users.xml</code>).</li>
|
||
|
|
<li><a href="#JAASRealm">JAASRealm</a> - Accesses authentication information
|
||
|
|
through the Java Authentication & Authorization Service (JAAS)
|
||
|
|
framework.</li>
|
||
|
|
</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:
|
||
|
|
<ul>
|
||
|
|
<li>Implement <code>org.apache.catalina.Realm</code>,</li>
|
||
|
|
<li>Place your compiled realm in $CATALINA_HOME/server/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>
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Configuring a Realm"><strong>Configuring a Realm</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>Before getting into the details of the standard Realm implementations, it is
|
||
|
|
important to understand, in general terms, how a Realm is configured. In
|
||
|
|
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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<Realm className="... class name for this implementation"
|
||
|
|
... other attributes for this implementation .../>
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
|
|
||
|
|
<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):
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li><em>Inside an <Engine> element</em> - This Realm will be shared
|
||
|
|
across ALL web applications on ALL virtual hosts, UNLESS it is overridden
|
||
|
|
by a Realm element nested inside a subordinate <code><Host></code>
|
||
|
|
or <code><Context></code> element.</li>
|
||
|
|
<li><em>Inside a <Host> element</em> - This Realm will be shared across
|
||
|
|
ALL web applications for THIS virtual host, UNLESS it is overridden
|
||
|
|
by a Realm element nested inside a subordinate <code><Context></code>
|
||
|
|
element.</li>
|
||
|
|
<li><em>Inside a <Context> element</em> - This Realm will be used ONLY
|
||
|
|
for THIS web application.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
|
||
|
|
</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="Common Features"><strong>Common Features</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Digested Passwords"><strong>Digested Passwords</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>For each of the standard <code>Realm</code> implementations, the
|
||
|
|
user's password (by default) is stored in clear text. In many
|
||
|
|
environments, this is undesireable because casual observers of the
|
||
|
|
authentication data can collect enough information to log on
|
||
|
|
successfully, and impersonate other users. To avoid this problem, the
|
||
|
|
standard implementations support the concept of <em>digesting</em>
|
||
|
|
user passwords. This allows the stored version of the passwords to be
|
||
|
|
encoded (in a form that is not easily reversible), but that the
|
||
|
|
<code>Realm</code> implementation can still utilize for
|
||
|
|
authentication.</p>
|
||
|
|
|
||
|
|
<p>When a standard realm authenticates by retrieving the stored
|
||
|
|
password and comparing it with the value presented by the user, you
|
||
|
|
can select digested passwords by specifying the <code>digest</code>
|
||
|
|
attribute on your <code><Realm></code> element. The value for
|
||
|
|
this attribute must be one of the digest algorithms supported by the
|
||
|
|
<code>java.security.MessageDigest</code> class (SHA, MD2, or MD5).
|
||
|
|
When you select this option, the contents of the password that is
|
||
|
|
stored in the <code>Realm</code> must be the cleartext version of the
|
||
|
|
password, as digested by the specified algorithm.</p>
|
||
|
|
|
||
|
|
<p>When the <code>authenticate()</code> method of the Realm is called, the
|
||
|
|
(cleartext) password specified by the user is itself digested by the same
|
||
|
|
algorithm, and the result is compared with the value returned by the
|
||
|
|
<code>Realm</code>. An equal match implies that the cleartext version of the
|
||
|
|
original password is the same as the one presented by the user, so that this
|
||
|
|
user should be authorized.</p>
|
||
|
|
|
||
|
|
<p>To calculate the digested value of a cleartext password, two convenience
|
||
|
|
techniques are supported:</p>
|
||
|
|
<ul>
|
||
|
|
<li>If you are writing an application that needs to calculate digested
|
||
|
|
passwords dynamically, call the static <code>Digest()</code> method of the
|
||
|
|
<code>org.apache.catalina.realm.RealmBase</code> class, passing the
|
||
|
|
cleartext password and the digest algorithm name as arguments. This
|
||
|
|
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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" 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" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
|
and the digested version of this cleartext password will be returned to
|
||
|
|
standard output.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>If using digested passwords with DIGEST authentication, the cleartext used
|
||
|
|
to generate the digest is different. In the examples above
|
||
|
|
<code>{cleartext-password}</code> must be replaced with
|
||
|
|
<code>{username}:{realm}:{cleartext-password}</code>. For example, in a
|
||
|
|
development environment this might take the form
|
||
|
|
<code>testUser:localhost:8080:testPassword</code>.</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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" 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" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></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
|
||
|
|
corrupted in the return, the digest will be invalid.</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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
|
||
|
|
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>
|
||
|
|
and log on with one of the usernames and passwords described for the default
|
||
|
|
<a href="#MemoryRealm">MemoryRealm</a>.</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Manager Application"><strong>Manager Application</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>If you wish to use the <a href="manager-howto.html">Manager Application</a>
|
||
|
|
to deploy and undeploy applications in a running Tomcat 6 installation, you
|
||
|
|
MUST add the "manager" role to at least one username in your selected Realm
|
||
|
|
implementation. This is because the manager web application itself uses a
|
||
|
|
security constraint that requires role "manager" to access ANY request URI
|
||
|
|
within that application.</p>
|
||
|
|
|
||
|
|
<p>For security reasons, no username in the default Realm (i.e. using
|
||
|
|
<code>conf/tomcat-users.xml</code> is assigned the "manager" role. Therfore,
|
||
|
|
no one will be able to utilize the features of this application until the
|
||
|
|
Tomcat administrator specifically assigns this role to one or more users.</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Realm Logging"><strong>Realm Logging</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>Debugging and exception messages logged by a <code>Realm</code> will
|
||
|
|
be recorded by the logging configuration associated with the container
|
||
|
|
for the realm: its surrounding <a href="config/context.html">Context</a>,
|
||
|
|
<a href="config/host.html">Host</a>, or
|
||
|
|
<a href="config/engine.html">Engine</a>.</p>
|
||
|
|
|
||
|
|
</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="Standard Realm Implementations"><strong>Standard Realm Implementations</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JDBCRealm"><strong>JDBCRealm</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<h3>Introduction</h3>
|
||
|
|
|
||
|
|
<p><strong>JDBCRealm</strong> is an implementation of the Tomcat 6
|
||
|
|
<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
|
||
|
|
database structure conforms to the following requirements:</p>
|
||
|
|
<ul>
|
||
|
|
<li>There must be a table, referenced below as the <em>users</em> table,
|
||
|
|
that contains one row for every valid user that this <code>Realm</code>
|
||
|
|
should recognize.</li>
|
||
|
|
<li>The <em>users</em> table must contain at least two columns (it may
|
||
|
|
contain more if your existing applications required it):
|
||
|
|
<ul>
|
||
|
|
<li>Username to be recognized by Tomcat when the user logs in.</li>
|
||
|
|
<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>
|
||
|
|
<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
|
||
|
|
one valid role.</li>
|
||
|
|
<li>The <em>user roles</em> table must contain at least two columns (it may
|
||
|
|
contain more if your existing applications required it):
|
||
|
|
<ul>
|
||
|
|
<li>Username to be recognized by Tomcat (same value as is specified
|
||
|
|
in the <em>users</em> table).</li>
|
||
|
|
<li>Role name of a valid role associated with this user.</li>
|
||
|
|
</ul></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Quick Start</h3>
|
||
|
|
|
||
|
|
<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
|
||
|
|
<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>Place a copy of the JDBC driver you will be using inside the
|
||
|
|
<code>$CATALINA_HOME/lib</code> directory.
|
||
|
|
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_HOME/conf/server.xml</code> file.</li>
|
||
|
|
<li>Restart Tomcat 6 if it is already running.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<h3>Realm Element Attributes</h3>
|
||
|
|
|
||
|
|
<p>To configure JDBCRealm, you will create a <code><Realm></code>
|
||
|
|
element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
|
||
|
|
as described <a href="#Configuring a Realm">above</a>. The following
|
||
|
|
attributes are supported by this implementation:</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">
|
||
|
|
<p>The fully qualified Java class name of this Realm implementation.
|
||
|
|
You <strong>MUST</strong> specify the value
|
||
|
|
"<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>connectionName</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The database username used to establish a JDBC connection.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>connectionPassword</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The database password used to establish a JDBC connection.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>connectionURL</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The database URL used to establish a JDBC connection.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>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. See
|
||
|
|
<a href="#Digested Passwords">Digested Passwords</a> for more
|
||
|
|
information. If not specified, passwords are stored in clear text.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>driverName</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The fully qualified Java class name of the JDBC driver to be used.
|
||
|
|
Consult the documentation for your JDBC driver for the appropriate
|
||
|
|
value.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>roleNameCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the column, in the <em>user roles</em> table, that
|
||
|
|
contains the name of a role assigned to this user.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userCredCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the column, in the <em>users</em> table, that contains
|
||
|
|
the password for this user (either in clear text, or digested if the
|
||
|
|
<code>digest</code> attribute is set).</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userNameCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the column, in the <em>users</em> and <em>user roles</em>
|
||
|
|
tables, that contains the username of this user.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userRoleTable</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the table that contains one row for each <em>role</em>
|
||
|
|
assigned to a particular <em>username</em>. This table must include at
|
||
|
|
least the columns named by the <code>userNameCol</code> and
|
||
|
|
<code>roleNameCol</code> attributes.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userTable</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the table that contains one row for each <em>username</em>
|
||
|
|
to be recognized by Tomcat. This table must include at least the columns
|
||
|
|
named by the <code>userNameCol</code> and <code>userCredCol</code>
|
||
|
|
attributes.</p>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<h3>Example</h3>
|
||
|
|
|
||
|
|
<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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
create table users (
|
||
|
|
user_name varchar(15) not null primary key,
|
||
|
|
user_pass varchar(15) not null
|
||
|
|
);
|
||
|
|
|
||
|
|
create table user_roles (
|
||
|
|
user_name varchar(15) not null,
|
||
|
|
role_name varchar(15) not null,
|
||
|
|
primary key (user_name, role_name)
|
||
|
|
);
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
|
|
||
|
|
<p>Example <code>Realm</code> elements are included (commented out) in the
|
||
|
|
default <code>$CATALINA_HOME/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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"
|
||
|
|
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" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></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
|
||
|
|
<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>
|
||
|
|
<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.
|
||
|
|
(For FORM-based authentication, that means until the session times out or
|
||
|
|
is invalidated; for BASIC authentication, that means until the user
|
||
|
|
closes their browser). The cached user is <strong>not</strong> saved and
|
||
|
|
restored across sessions serialisations. Any changes to the database
|
||
|
|
information for an already authenticated user will <strong>not</strong> be
|
||
|
|
reflected until the next time that user logs on again.</li>
|
||
|
|
<li>Administering the information in the <em>users</em> and <em>user roles</em>
|
||
|
|
table is the responsibility of your own applications. Tomcat does not
|
||
|
|
provide any built-in capabilities to maintain users and roles.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="DataSourceRealm"><strong>DataSourceRealm</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<h3>Introduction</h3>
|
||
|
|
|
||
|
|
<p><strong>DataSourceRealm</strong> is an implementation of the Tomcat 6
|
||
|
|
<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
|
||
|
|
as your database structure conforms to the following requirements:</p>
|
||
|
|
<ul>
|
||
|
|
<li>There must be a table, referenced below as the <em>users</em> table,
|
||
|
|
that contains one row for every valid user that this <code>Realm</code>
|
||
|
|
should recognize.</li>
|
||
|
|
<li>The <em>users</em> table must contain at least two columns (it may
|
||
|
|
contain more if your existing applications required it):
|
||
|
|
<ul>
|
||
|
|
<li>Username to be recognized by Tomcat when the user logs in.</li>
|
||
|
|
<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>
|
||
|
|
<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
|
||
|
|
one valid role.</li>
|
||
|
|
<li>The <em>user roles</em> table must contain at least two columns (it may
|
||
|
|
contain more if your existing applications required it):
|
||
|
|
<ul>
|
||
|
|
<li>Username to be recognized by Tomcat (same value as is specified
|
||
|
|
in the <em>users</em> table).</li>
|
||
|
|
<li>Role name of a valid role associated with this user.</li>
|
||
|
|
</ul></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Quick Start</h3>
|
||
|
|
|
||
|
|
<p>To set up Tomcat to use DataSourceRealm, you will need to follow these steps:</p>
|
||
|
|
<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>
|
||
|
|
<li>Set up a <code><Realm></code> element, as described below, in your
|
||
|
|
<code>$CATALINA_HOME/conf/server.xml</code> file.</li>
|
||
|
|
<li>Restart Tomcat 6 if it is already running.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<h3>Realm Element Attributes</h3>
|
||
|
|
|
||
|
|
<p>To configure DataSourceRealm, you will create a <code><Realm></code>
|
||
|
|
element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
|
||
|
|
as described <a href="#Configuring a Realm">above</a>. The following
|
||
|
|
attributes are supported by this implementation:</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">
|
||
|
|
<p>The fully qualified Java class name of this Realm implementation.
|
||
|
|
You <strong>MUST</strong> specify the value
|
||
|
|
"<code>org.apache.catalina.realm.DataSourceRealm</code>" here.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>dataSourceName</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The JNDI named JDBC DataSource for your database. If the DataSource is
|
||
|
|
local to the context, the name is relative to <code>java:/comp/env</code>,
|
||
|
|
and otherwise the name should match the name used to define the global
|
||
|
|
DataSource.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>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. See
|
||
|
|
<a href="#Digested Passwords">Digested Passwords</a> for more
|
||
|
|
information. If not specified, passwords are 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
|
||
|
|
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
|
||
|
|
global DataSource.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>roleNameCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the column, in the <em>user roles</em> table, that
|
||
|
|
contains the name of a role assigned to this user.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userCredCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the column, in the <em>users</em> table, that contains
|
||
|
|
the password for this user (either in clear text, or digested if the
|
||
|
|
<code>digest</code> attribute is set).</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userNameCol</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the column, in the <em>users</em> and <em>user roles</em>
|
||
|
|
tables, that contains the username of this user.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userRoleTable</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the table that contains one row for each <em>role</em>
|
||
|
|
assigned to a particular <em>username</em>. This table must include at
|
||
|
|
least the columns named by the <code>userNameCol</code> and
|
||
|
|
<code>roleNameCol</code> attributes.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>userTable</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the table that contains one row for each <em>username</em>
|
||
|
|
to be recognized by Tomcat. This table must include at least the columns
|
||
|
|
named by the <code>userNameCol</code> and <code>userCredCol</code>
|
||
|
|
attributes.</p>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<h3>Example</h3>
|
||
|
|
|
||
|
|
<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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
create table users (
|
||
|
|
user_name varchar(15) not null primary key,
|
||
|
|
user_pass varchar(15) not null
|
||
|
|
);
|
||
|
|
|
||
|
|
create table user_roles (
|
||
|
|
user_name varchar(15) not null,
|
||
|
|
role_name varchar(15) not null,
|
||
|
|
primary key (user_name, role_name)
|
||
|
|
);
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99"
|
||
|
|
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" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></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
|
||
|
|
<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>
|
||
|
|
<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.
|
||
|
|
(For FORM-based authentication, that means until the session times out or
|
||
|
|
is invalidated; for BASIC authentication, that means until the user
|
||
|
|
closes their browser). The cached user is <strong>not</strong> saved and
|
||
|
|
restored across sessions serialisations. Any changes to the database
|
||
|
|
information for an already authenticated user will <strong>not</strong> be
|
||
|
|
reflected until the next time that user logs on again.</li>
|
||
|
|
<li>Administering the information in the <em>users</em> and <em>user roles</em>
|
||
|
|
table is the responsibility of your own applications. Tomcat does not
|
||
|
|
provide any built-in capabilities to maintain users and roles.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JNDIRealm"><strong>JNDIRealm</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<h3>Introduction</h3>
|
||
|
|
|
||
|
|
<p><strong>JNDIRealm</strong> is an implementation of the Tomcat 6
|
||
|
|
<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
|
||
|
|
supports a variety of approaches to using a directory for
|
||
|
|
authentication.</p>
|
||
|
|
|
||
|
|
<h4>Connecting to the directory</h4>
|
||
|
|
|
||
|
|
<p>The realm's connection to the directory is defined by the
|
||
|
|
<strong>connectionURL</strong> configuration attribute. This is a URL
|
||
|
|
whose format is defined by the JNDI provider. It is usually an LDAP
|
||
|
|
URL that specifies the domain name of the directory server to connect
|
||
|
|
to, and optionally the port number and distinguished name (DN) of the
|
||
|
|
required root naming context.</p>
|
||
|
|
|
||
|
|
<p>If you have more than one provider you can configure an
|
||
|
|
<strong>alternateURL</strong>. If a socket connection can not be
|
||
|
|
made to the provider at the <strong>connectionURL</strong> an
|
||
|
|
attempt will be made to use the <strong>alternateURL</strong>.</p>
|
||
|
|
|
||
|
|
<p>When making a connection in order to search the directory and
|
||
|
|
retrieve user and role information, the realm authenticates itself to
|
||
|
|
the directory with the username and password specified by the
|
||
|
|
<strong>connectionName</strong> and
|
||
|
|
<strong>connectionPassword</strong> properties. If these properties
|
||
|
|
are not specified the connection is anonymous. This is sufficient in
|
||
|
|
many cases.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4>Selecting the user's directory entry</h4>
|
||
|
|
|
||
|
|
<p>Each user that can be authenticated must be represented in the
|
||
|
|
directory by an individual entry that corresponds to an element in the
|
||
|
|
initial <code>DirContext</code> defined by the
|
||
|
|
<strong>connectionURL</strong> attribute. This user entry must have an
|
||
|
|
attribute containing the username that is presented for
|
||
|
|
authentication.</p>
|
||
|
|
|
||
|
|
<p>Often the distinguished name of the user's entry contains the
|
||
|
|
username presented for authentication but is otherwise the same for
|
||
|
|
all users. In this case the <strong>userPattern</strong> attribute may
|
||
|
|
be used to specify the DN, with "{0}" marking where
|
||
|
|
the username should be substituted.</p>
|
||
|
|
|
||
|
|
<p>Otherwise the realm must search the directory to find a unique entry
|
||
|
|
containing the username. The following attributes configure this
|
||
|
|
search:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><strong>userBase</strong> - the entry that is the base of
|
||
|
|
the subtree containing users. If not specified, the search
|
||
|
|
base is the top-level context.</li>
|
||
|
|
|
||
|
|
<li><strong>userSubtree</strong> - the search scope. Set to
|
||
|
|
<code>true</code> if you wish to search the entire subtree
|
||
|
|
rooted at the <strong>userBase</strong> entry. The default value
|
||
|
|
of <code>false</code> requests a single-level search
|
||
|
|
including only the top level.</li>
|
||
|
|
|
||
|
|
<li><strong>userSearch</strong> - pattern specifying the LDAP
|
||
|
|
search filter to use after substitution of the username.</li>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4>Authenticating the user</h4>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<p><b>Bind mode</b></p>
|
||
|
|
|
||
|
|
<p>By default the realm authenticates a user by binding to
|
||
|
|
the directory with the DN of the entry for that user and the password
|
||
|
|
presented by the user. If this simple bind succeeds the user is considered to
|
||
|
|
be authenticated.</p>
|
||
|
|
|
||
|
|
<p>For security reasons a directory may store a digest of the user's
|
||
|
|
password rather than the clear text version (see <a href="#Digested Passwords">Digested Passwords</a> for more information). In that case,
|
||
|
|
as part of the simple bind operation the directory automatically
|
||
|
|
computes the correct digest of the plaintext password presented by the
|
||
|
|
user before validating it against the stored value. In bind mode,
|
||
|
|
therefore, the realm is not involved in digest processing. The
|
||
|
|
<strong>digest</strong> attribute is not used, and will be ignored if
|
||
|
|
set.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>
|
||
|
|
<p><b>Comparison mode</b></p>
|
||
|
|
<p>Alternatively, the realm may retrieve the stored
|
||
|
|
password from the directory and compare it explicitly with the value
|
||
|
|
presented by the user. This mode is configured by setting the
|
||
|
|
<strong>userPassword</strong> attribute to the name of a directory
|
||
|
|
attribute in the user's entry that contains the password.</p>
|
||
|
|
|
||
|
|
<p>Comparison mode has some disadvantages. First, the
|
||
|
|
<strong>connectionName</strong> and
|
||
|
|
<strong>connectionPassword</strong> attributes must be configured to
|
||
|
|
allow the realm to read users' passwords in the directory. For
|
||
|
|
security reasons this is generally undesirable; indeed many directory
|
||
|
|
implementations will not allow even the directory manager to read
|
||
|
|
these passwords. In addition, the realm must handle password digests
|
||
|
|
itself, including variations in the algorithms used and ways of
|
||
|
|
representing password hashes in the directory. However, the realm may
|
||
|
|
sometimes need access to the stored password, for example to support
|
||
|
|
HTTP Digest Access Authentication (RFC 2069). (Note that HTTP digest
|
||
|
|
authentication is different from the storage of password digests in
|
||
|
|
the repository for user information as discussed above).
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h4>Assigning roles to the user</h4>
|
||
|
|
|
||
|
|
<p>The directory realm supports two approaches to the representation
|
||
|
|
of roles in the directory:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<p><b>Roles as explicit directory entries</b></p>
|
||
|
|
|
||
|
|
<p>Roles may be represented by explicit directory entries. A role
|
||
|
|
entry is usually an LDAP group entry with one attribute
|
||
|
|
containing the name of the role and another whose values are the
|
||
|
|
distinguished names or usernames of the users in that role. The
|
||
|
|
following attributes configure a directory search to
|
||
|
|
find the names of roles associated with the authenticated user:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><strong>roleBase</strong> - the base entry for the role search.
|
||
|
|
If not specified, the search base is the top-level directory
|
||
|
|
context.</li>
|
||
|
|
|
||
|
|
<li><strong>roleSubtree</strong> - the search
|
||
|
|
scope. Set to <code>true</code> if you wish to search the entire
|
||
|
|
subtree rooted at the <code>roleBase</code> entry. The default
|
||
|
|
value of <code>false</code> requests a single-level search
|
||
|
|
including the top level only.</li>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<li><strong>roleName</strong> - the attribute in a role entry
|
||
|
|
containing the name of that role.</li>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<p><b>Roles as an attribute of the user entry</b></p>
|
||
|
|
|
||
|
|
<p>Role names may also be held as the values of an attribute in the
|
||
|
|
user's directory entry. Use <strong>userRoleName</strong> to specify
|
||
|
|
the name of this attribute.</p>
|
||
|
|
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>A combination of both approaches to role representation may be used.</p>
|
||
|
|
|
||
|
|
<h3>Quick Start</h3>
|
||
|
|
|
||
|
|
<p>To set up Tomcat to use JNDIRealm, you will need to follow these steps:</p>
|
||
|
|
<ol>
|
||
|
|
<li>Make sure your directory server is configured with a schema that matches
|
||
|
|
the requirements listed above.</li>
|
||
|
|
<li>If required, configure a username and password for use by Tomcat, that has
|
||
|
|
read only access to the information described above. (Tomcat will
|
||
|
|
never attempt to modify this information.)</li>
|
||
|
|
<li>Place a copy of the JNDI driver you will be using (typically
|
||
|
|
<code>ldap.jar</code> available with JNDI) inside the
|
||
|
|
<code>$CATALINA_HOME/lib</code> directory.</li>
|
||
|
|
<li>Set up a <code><Realm></code> element, as described below, in your
|
||
|
|
<code>$CATALINA_HOME/conf/server.xml</code> file.</li>
|
||
|
|
<li>Restart Tomcat 6 if it is already running.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<h3>Realm Element Attributes</h3>
|
||
|
|
|
||
|
|
<p>To configure JNDIRealm, you will create a <code><Realm></code>
|
||
|
|
element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
|
||
|
|
as described <a href="#Configuring a Realm">above</a>. The following
|
||
|
|
attributes are supported by this implementation:</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">
|
||
|
|
<p>The fully qualified Java class name of this Realm implementation.
|
||
|
|
You <strong>MUST</strong> specify the value
|
||
|
|
"<code>org.apache.catalina.realm.JNDIRealm</code>" here.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>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">
|
||
|
|
<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"><strong><code>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">
|
||
|
|
<p>The fully qualified Java class name of the JNDI context
|
||
|
|
factory to be used for this connection. By default, the standard
|
||
|
|
JNDI LDAP provider is used
|
||
|
|
(<code>com.sun.jndi.ldap.LdapCtxFactory</code>).</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>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. See <a href="#Digested Passwords">Digested Passwords</a> for more
|
||
|
|
information. 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>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">
|
||
|
|
<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
|
||
|
|
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">
|
||
|
|
<p>The LDAP filter expression used for performing role
|
||
|
|
searches, following the syntax supported by the
|
||
|
|
<code>java.text.MessageFormat</code> class. 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">
|
||
|
|
<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">
|
||
|
|
<p>The base element for user searches performed using the
|
||
|
|
<code>userSearch</code> expression. If not specified, the top
|
||
|
|
level element in the directory context will be used. 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">
|
||
|
|
<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
|
||
|
|
<code>connectionName</code> and
|
||
|
|
<code>connectionPassword</code> properties, and retrieve the
|
||
|
|
corresponding attribute for comparison to the value specified
|
||
|
|
by the user being authenticated. If the <code>digest</code>
|
||
|
|
attribute is set, the specified digest algorithm is applied to
|
||
|
|
the password offered by the user before comparing it with the
|
||
|
|
value retrieved from the directory. If you do
|
||
|
|
<strong>not</strong> specify this value, JNDIRealm will
|
||
|
|
attempt a simple bind to the directory using the DN of the
|
||
|
|
user's entry and password specified 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">
|
||
|
|
<p>A pattern for the distinguished name (DN) of the user's
|
||
|
|
directory entry, following the syntax supported by the
|
||
|
|
<code>java.text.MessageFormat</code> class 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">
|
||
|
|
<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
|
||
|
|
<code>roleName</code> property to specify the name of an
|
||
|
|
attribute to be retrieved from individual role entries found
|
||
|
|
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">
|
||
|
|
<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
|
||
|
|
(along with the <code>userBase</code> and
|
||
|
|
<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">
|
||
|
|
<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></table>
|
||
|
|
|
||
|
|
<h3>Example</h3>
|
||
|
|
|
||
|
|
<p>Creation of the appropriate schema in your directory server is beyond the
|
||
|
|
scope of this document, because it is unique to each directory server
|
||
|
|
implementation. In the examples below, we will assume that you are using a
|
||
|
|
distribution of the OpenLDAP directory server (version 2.0.11 or later), which
|
||
|
|
can be downloaded from
|
||
|
|
<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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
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" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></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>
|
||
|
|
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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
|
||
|
|
# Define top-level entry
|
||
|
|
dn: dc=mycompany,dc=com
|
||
|
|
objectClass: dcObject
|
||
|
|
dc:mycompany
|
||
|
|
|
||
|
|
# Define an entry to contain people
|
||
|
|
# searches for users are based on this entry
|
||
|
|
dn: ou=people,dc=mycompany,dc=com
|
||
|
|
objectClass: organizationalUnit
|
||
|
|
ou: people
|
||
|
|
|
||
|
|
# Define a user entry for Janet Jones
|
||
|
|
dn: uid=jjones,ou=people,dc=mycompany,dc=com
|
||
|
|
objectClass: inetOrgPerson
|
||
|
|
uid: jjones
|
||
|
|
sn: jones
|
||
|
|
cn: janet jones
|
||
|
|
mail: j.jones@mycompany.com
|
||
|
|
userPassword: janet
|
||
|
|
|
||
|
|
# Define a user entry for Fred Bloggs
|
||
|
|
dn: uid=fbloggs,ou=people,dc=mycompany,dc=com
|
||
|
|
objectClass: inetOrgPerson
|
||
|
|
uid: fbloggs
|
||
|
|
sn: bloggs
|
||
|
|
cn: fred bloggs
|
||
|
|
mail: f.bloggs@mycompany.com
|
||
|
|
userPassword: fred
|
||
|
|
|
||
|
|
# Define an entry to contain LDAP groups
|
||
|
|
# searches for roles are based on this entry
|
||
|
|
dn: ou=groups,dc=mycompany,dc=com
|
||
|
|
objectClass: organizationalUnit
|
||
|
|
ou: groups
|
||
|
|
|
||
|
|
# Define an entry for the "tomcat" role
|
||
|
|
dn: cn=tomcat,ou=groups,dc=mycompany,dc=com
|
||
|
|
objectClass: groupOfUniqueNames
|
||
|
|
cn: tomcat
|
||
|
|
uniqueMember: uid=jjones,ou=people,dc=mycompany,dc=com
|
||
|
|
uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com
|
||
|
|
|
||
|
|
# Define an entry for the "role1" role
|
||
|
|
dn: cn=role1,ou=groups,dc=mycompany,dc=com
|
||
|
|
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" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
|
|
||
|
|
<p>An example <code>Realm</code> element for the OpenLDAP directory
|
||
|
|
server configured as described above might look like this, assuming
|
||
|
|
that users use their uid (e.g. jjones) to login to the
|
||
|
|
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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<Realm className="org.apache.catalina.realm.JNDIRealm" debug="99"
|
||
|
|
connectionURL="ldap://localhost:389"
|
||
|
|
userPattern="uid={0},ou=people,dc=mycompany,dc=com"
|
||
|
|
roleBase="ou=groups,dc=mycompany,dc=com"
|
||
|
|
roleName="cn"
|
||
|
|
roleSearch="(uniqueMember={0})"
|
||
|
|
/>
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
|
|
||
|
|
<p>With this configuration, the realm will determine the user's
|
||
|
|
distinguished name by substituting the username into the
|
||
|
|
<code>userPattern</code>, authenticate by binding to the directory
|
||
|
|
with this DN and the password received from the user, and search the
|
||
|
|
directory to find the user's roles.</p>
|
||
|
|
|
||
|
|
<p>Now suppose that users are expected to enter their email address
|
||
|
|
rather than their userid when logging in. In this case the realm must
|
||
|
|
search the directory for the user's entry. (A search is also necessary
|
||
|
|
when user entries are held in multiple subtrees corresponding perhaps
|
||
|
|
to different organizational units or company locations).</p>
|
||
|
|
|
||
|
|
<p>Further, suppose that in addition to the group entries you want to
|
||
|
|
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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
dn: uid=jjones,ou=people,dc=mycompany,dc=com
|
||
|
|
objectClass: inetOrgPerson
|
||
|
|
uid: jjones
|
||
|
|
sn: jones
|
||
|
|
cn: janet jones
|
||
|
|
mail: j.jones@mycompany.com
|
||
|
|
memberOf: role2
|
||
|
|
memberOf: role3
|
||
|
|
userPassword: janet
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<Realm className="org.apache.catalina.realm.JNDIRealm" debug="99"
|
||
|
|
connectionURL="ldap://localhost:389"
|
||
|
|
userBase="ou=people,dc=mycompany,dc=com"
|
||
|
|
userSearch="(mail={0})"
|
||
|
|
userRoleName="memberOf"
|
||
|
|
roleBase="ou=groups,dc=mycompany,dc=com"
|
||
|
|
roleName="cn"
|
||
|
|
roleSearch="(uniqueMember={0})"
|
||
|
|
/>
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></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
|
||
|
|
attribute and attempts to bind to the directory as
|
||
|
|
<code>uid=jjones,ou=people,dc=mycompany,dc=com</code> with the given
|
||
|
|
password. If authentication succeeds, she is assigned three roles:
|
||
|
|
"role2" and "role3", the values of the "memberOf" attribute in her
|
||
|
|
directory entry, and "tomcat", the value of the "cn" attribute in the
|
||
|
|
only group entry of which she is a member.</p>
|
||
|
|
|
||
|
|
<p>Finally, to authenticate the user by retrieving
|
||
|
|
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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<Realm className="org.apache.catalina.realm.JNDIRealm" debug="99"
|
||
|
|
connectionName="cn=Manager,dc=mycompany,dc=com"
|
||
|
|
connectionPassword="secret"
|
||
|
|
connectionURL="ldap://localhost:389"
|
||
|
|
userPassword="userPassword"
|
||
|
|
userPattern="uid={0},ou=people,dc=mycompany,dc=com"
|
||
|
|
roleBase="ou=groups,dc=mycompany,dc=com"
|
||
|
|
roleName="cn"
|
||
|
|
roleSearch="(uniqueMember={0})"
|
||
|
|
/>
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
|
|
||
|
|
<p>However, as discussed above, the default bind mode for
|
||
|
|
authentication is usually to be preferred.</p>
|
||
|
|
|
||
|
|
<h3>Additional Notes</h3>
|
||
|
|
|
||
|
|
<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
|
||
|
|
<code>Realm</code>. Thus, any changes you have made to the directory
|
||
|
|
(new users, changed passwords or roles, etc.) will be immediately
|
||
|
|
reflected.</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.
|
||
|
|
(For FORM-based authentication, that means until the session times out or
|
||
|
|
is invalidated; for BASIC authentication, that means until the user
|
||
|
|
closes their browser). The cached user is <strong>not</strong> saved and
|
||
|
|
restored across sessions serialisations. Any changes to the directory
|
||
|
|
information for an already authenticated user will <strong>not</strong> be
|
||
|
|
reflected until the next time that user logs on again.</li>
|
||
|
|
<li>Administering the information in the directory server
|
||
|
|
is the responsibility of your own applications. Tomcat does not
|
||
|
|
provide any built-in capabilities to maintain users and roles.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="MemoryRealm"><strong>MemoryRealm</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<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.
|
||
|
|
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_HOME/conf/tomcat-users.xml</code>). Changes to the data
|
||
|
|
in this file are not recognized until Tomcat is restarted.</p>
|
||
|
|
|
||
|
|
<h3>Realm Element Attributes</h3>
|
||
|
|
|
||
|
|
<p>To configure MemoryRealm, you will create a <code><Realm></code>
|
||
|
|
element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
|
||
|
|
as described <a href="#Configuring a Realm">above</a>. The following
|
||
|
|
attributes are supported by this implementation:</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">
|
||
|
|
<p>The fully qualified Java class name of this Realm implementation.
|
||
|
|
You <strong>MUST</strong> specify the value
|
||
|
|
"<code>org.apache.catalina.realm.MemoryRealm</code>" here.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>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. See
|
||
|
|
<a href="#Digested Passwords">Digested Passwords</a> for more
|
||
|
|
information. 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_HOME) pathname of the XML document
|
||
|
|
containing our valid usernames, passwords, and roles. See below for more
|
||
|
|
information on the format of this file. If not specified, the value
|
||
|
|
<code>conf/tomcat-users.xml</code> is used.</p>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<h3>User File Format</h3>
|
||
|
|
|
||
|
|
<p>The users file (by default, <code>conf/tomcat-users.xml</code> must be an
|
||
|
|
XML document, with a root element <code><tomcat-users></code>. Nested
|
||
|
|
inside the root element will be a <code><user></code> element for each
|
||
|
|
valid user, consisting of the following attributes:</p>
|
||
|
|
<ul>
|
||
|
|
<li><strong>name</strong> - Username this user must log on with.</li>
|
||
|
|
<li><strong>password</strong> - Password this user must log on with (in
|
||
|
|
clear text if the <code>digest</code> attribute was not set on the
|
||
|
|
<code><Realm></code> element, or digested appropriately as
|
||
|
|
described <a href="#Digested Passwords">here</a> otherwise).</li>
|
||
|
|
<li><strong>roles</strong> - Comma-delimited list of the role names
|
||
|
|
associated with this user.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Example</h3>
|
||
|
|
|
||
|
|
<p>The default installation of Tomcat 6 is configured with a MemoryRealm
|
||
|
|
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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<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" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
|
|
||
|
|
<h3>Additional Notes</h3>
|
||
|
|
|
||
|
|
<p>MemoryRealm operates according to the following rules:</p>
|
||
|
|
<ul>
|
||
|
|
<li>When Tomcat first starts up, it loads all defined users and their
|
||
|
|
associated information from the users file. Changes to the data in
|
||
|
|
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
|
||
|
|
<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.
|
||
|
|
(For FORM-based authentication, that means until the session times out or
|
||
|
|
is invalidated; for BASIC authentication, that means until the user
|
||
|
|
closes their browser). The cached user is <strong>not</strong> saved and
|
||
|
|
restored across sessions serialisations.</li>
|
||
|
|
<li>Administering the information in the users file is the responsibility
|
||
|
|
of your application. Tomcat does not
|
||
|
|
provide any built-in capabilities to maintain users and roles.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JAASRealm"><strong>JAASRealm</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<h3>Introduction</h3>
|
||
|
|
|
||
|
|
<p><strong>JAASRealm</strong> is an implementation of the Tomcat
|
||
|
|
4 <code>Realm</code> interface that authenticates users through the Java
|
||
|
|
Authentication & Authorization Service (JAAS) framework, a Java
|
||
|
|
package that is available as an optional package in Java 2 SDK 1.3 and
|
||
|
|
is fully integrated as of SDK 1.4 .</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 proposed JAAS-based
|
||
|
|
J2EE authentication framework for J2EE v1.4, based on the <a href="http://www.jcp.org/en/jsr/detail?id=196">JCP Specification
|
||
|
|
Request 196</a> to enhance container-managed security and promote
|
||
|
|
'pluggable' authentication mechanisms whose implementations would be
|
||
|
|
container-independent.
|
||
|
|
</p>
|
||
|
|
<p>Based on the JAAS login module and principal (see <code>javax.security.auth.spi.LoginModule</code>
|
||
|
|
and <code>javax.security.Principal</code>), you can develop your own
|
||
|
|
security mechanism or wrap another third-party mechanism for
|
||
|
|
integration with the CMA as implemented by Tomcat.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h3>Quick Start</h3>
|
||
|
|
<p>To set up Tomcat to use JAASRealm with your own JAAS login module,
|
||
|
|
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://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/GeneralAcnOnly.html">the
|
||
|
|
JAAS Authentication Tutorial</a> and
|
||
|
|
<a href="http://java.sun.com/j2se/1.4.1/docs/guide/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>,
|
||
|
|
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://java.sun.com/j2se/1.4.1/docs/guide/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=-DJAVA_OPTS=-Djava.security.auth.login.config==$CATALINA_HOME/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>
|
||
|
|
</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
|
||
|
|
<code>$CATALINA_HOME/conf/server.xml</code>
|
||
|
|
file within your <code><Engine></code> node. The following attributes
|
||
|
|
are supported by this implementation:</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">
|
||
|
|
<p>The fully qualified Java class name of this Realm implementation.
|
||
|
|
You <strong>MUST</strong> specify the value
|
||
|
|
"<code>org.apache.catalina.realm.JAASRealm</code>" here.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>appName</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The name of the application as configured in your login configuration file
|
||
|
|
(<a href="http://java.sun.com/j2se/1.4.1/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-seperated 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-seperated 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">
|
||
|
|
<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 4 works. To load classes using the container's classloader, specify
|
||
|
|
<code>false</code>.</p>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<h3>Example</h3>
|
||
|
|
|
||
|
|
<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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<Realm className="org.apache.catalina.realm.JAASRealm"
|
||
|
|
appName="MyFooRealm"
|
||
|
|
userClassNames="org.foobar.realm.FooUser"
|
||
|
|
roleClassNames="org.foobar.realm.FooRole"
|
||
|
|
debug="99"/>
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></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
|
||
|
|
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
|
||
|
|
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>
|
||
|
|
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>
|
||
|
|
<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. For FORM-based authentication, that means until
|
||
|
|
the session times out or is invalidated; for BASIC authentication,
|
||
|
|
that means until the user closes their browser. Any changes to the
|
||
|
|
security information for an already authenticated user will <strong>not</strong>
|
||
|
|
be reflected until the next time that user logs on again.</li>
|
||
|
|
<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>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</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-2006, Apache Software Foundation
|
||
|
|
</em></font></div></td></tr></table></body></html>
|