source: nutchez-0.1/tomcat/webapps/docs/funcspecs/fs-jndi-realm.html @ 261

Last change on this file since 261 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 21.0 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications - JNDIRealm</title><meta value="Craig McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2      Catalina Functional Specifications
3    " align="right" src="../images/tomcat.gif"></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 border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Functional Specs</a></li></ul><p><strong>Administrative Apps</strong></p><ul><li><a href="fs-admin-apps.html">Overall Requirements</a></li><li><a href="mbean-names.html">Tomcat MBean Names</a></li><li><a href="fs-admin-objects.html">Administered Objects</a></li><li><a href="fs-admin-opers.html">Supported Operations</a></li></ul><p><strong>Internal Servlets</strong></p><ul><li><a href="fs-default.html">Default Servlet</a></li><li><a href="fs-invoker.html">Invoker Servlet</a></li></ul><p><strong>Realm Implementations</strong></p><ul><li><a href="fs-jdbc-realm.html">JDBC Realm</a></li><li><a href="fs-jndi-realm.html">JNDI Realm</a></li><li><a href="fs-memory-realm.html">Memory Realm</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Catalina Functional Specifications</h1><h2>JNDIRealm</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/fs-jndi-realm.html"><img alt="Printer Friendly Version" border="0" src="../images/printer.gif"><br>print-friendly<br>version
4                    </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
5
6
7  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
8
9    <p>The purpose of the <strong>JNDIRealm</strong> implementation is to
10    provide a mechanism by which Tomcat 6 can acquire information needed
11    to authenticate web application users, and define their security roles,
12    from a directory server or other service accessed via JNDI APIs.  For
13    integration with Catalina, this class must implement the
14    <code>org.apache.catalina.Realm</code> interface.</p>
15
16    <p>This specification reflects a combination of functionality that is
17    already present in the <code>org.apache.catalina.realm.JNDIRealm</code>
18    class, as well as requirements for enhancements that have been
19    discussed.  Where appropriate, requirements statements are marked
20    <em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>
21
22    <p>The current status of this functional specification is
23    <strong>PROPOSED</strong>.  It has not yet been discussed and
24    agreed to on the TOMCAT-DEV mailing list.</p>
25
26    <p>The code in the current version of <code>JNDIRealm</code>, and the
27    ideas expressed in this functional specification, are the results of
28    contributions from many individuals, including (alphabetically):</p>
29    <ul>
30    <li>Holman, John &lt;j.g.holman@qmw.ac.uk&gt;</li>
31    <li>Lockhart, Ellen &lt;elockhart@home.com&gt;</li>
32    <li>McClanahan, Craig &lt;craigmcc@apache.org&gt;</li>
33    </ul>
34
35  </blockquote></td></tr></table>
36
37
38  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="External Specifications"><strong>External Specifications</strong></a></font></td></tr><tr><td><blockquote>
39
40    <p>The implementation of this functionality depends on the following
41    external specifications:</p>
42    <ul>
43    <li><a href="http://java.sun.com/products/jndi/">Java Naming and
44        Directory Interface</a> (version 1.2.1 or later)</li>
45    </ul>
46
47  </blockquote></td></tr></table>
48
49
50  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Implementation Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote>
51
52    <p>The implementation of this functionality shall conform to the
53    following requirements:</p>
54    <ul>
55    <li>Be realized in one or more implementation classes.</li>
56    <li>Implement the <code>org.apache.catalina.Realm</code> interface.
57        [Current]</li>
58    <li>Implement the <code>org.apache.catalina.Lifecycle</code>
59        interface.  [Current]</li>
60    <li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
61        base class.</li>
62    <li>Live in the <code>org.apache.catalina.realm</code> package.
63        [Current]</li>
64    <li>Support a configurable debugging detail level. [Current]</li>
65    <li>Log debugging and operational messages (suitably internationalized)
66        via the <code>getContainer().log()</code> method. [Current]</li>
67    </ul>
68
69  </blockquote></td></tr></table>
70
71
72</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote>
73
74
75  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Environmental Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote>
76
77    <p>The following environmental dependencies must be met in order for
78    JNDIRealm to operate correctly:</p>
79    <ul>
80    <li>The desire to utilize JNDIRealm must be registered in
81        <code>$CATALINA_BASE/conf/server.xml</code>, in a
82        <code>&lt;Realm&gt;</code> element that is nested inside a
83        corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
84        or <code>&lt;Context&gt;</code> element.</li>
85    <li>If the <em>Administrator Login</em> operational mode is selected,
86        the configured administrator username and password must be configured
87        in the corresponding directory server.</li>
88    <li>If the <em>Username Login</em> operational mode is selected,
89        the corresponding directory server must be configured to accept
90        logins with the username and password that will be passed to
91        <code>JNDIRealm</code> by the appropriate <code>Authenticator</code>.
92        </li>
93    </ul>
94
95  </blockquote></td></tr></table>
96
97
98  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Container Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>
99
100    <p>Correct operation of JNDIRealm depends on the following
101    specific features of the surrounding container:</p>
102    <ul>
103    <li>Interactions with <code>JNDIRealm</code> will be initiated by
104        the appropriate <code>Authenticator</code> implementation, based
105        on the login method that is selected.</li>
106    <li><code>JNDIRealm</code> must have the JNDI API classes available
107        to it.  For a JDK 1.2 container, that means <code>jndi.jar</code>
108        and the appropriate implementation (such as <code>ldap.jar</code>)
109        must be placed in the <code>server/lib</code> directory.</li>
110    </ul>
111
112  </blockquote></td></tr></table>
113
114
115</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote>
116
117
118  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Operational Modes"><strong>Operational Modes</strong></a></font></td></tr><tr><td><blockquote>
119
120    <p>The completed <code>JNDIRealm</code> must support two major operational
121    modes in order to support all of the required use cases.  For the purposes
122    of this document, the modes are called <em>administrator login</em> and
123    <em>Username Login</em>.  They are described further in the following
124    paragraphs.</p>
125
126    <p>For <em>Administrator Login</em> mode, <code>JNDIRealm</code> will be
127    configured to establish one or more connections (using a connection pool)
128    to an appropriate directory server, using JNDI APIs, under a "system
129    administrator" username and password.  This is similar to the approach
130    normally used to configure <code>JDBCRealm</code> to access authentication
131    and access control information in a database.  It is assumed that the
132    system administrator username and password that are configured provide
133    sufficient privileges within the directory server to read (but not modify)
134    the username, password, and assigned roles for each valid user of the
135    web application associated with this <code>Realm</code>.  The password
136    can be stored in cleartext, or in one of the digested modes supported by
137    the <code>org.apache.catalina.realm.RealmBase</code> base class.</p>
138
139    <p>For <em>Username Login</em> mode, <code>JNDIRealm</code> does not
140    normally remain connected to the directory server.  Instead, whenever a
141    user is to be authenticated, a connection to the directory server
142    (using the username and password received from the authenticator) is
143    attempted.  If this connection is successful, the user is assumed to be
144    successfully authenticated.  This connection is then utilized to read
145    the corresponding security roles associated with this user, and the
146    connection is then broken.</p>
147
148    <p><strong>NOTE</strong> - <em>Username Login</em> mode cannot be used
149    if you have selected login method <code>DIGEST</code> in your web
150    application deployment descriptor (<code>web.xml</code>) file.  This
151    restriction exists because the cleartext password is never available
152    to the container, so it is not possible to bind to the directory server
153    using the user's username and password.</p>
154
155    <p>Because these operational modes work so differently, the functionality
156    for each mode will be described separately.  Whether or not both modes
157    are actually supported by a single class (versus a class per mode) is
158    an implementation detail left to the designer.</p>
159
160    <p><strong>NOTE</strong> - The current implementation only implements
161    part of the <em>Administrator Lookup</em> mode requirements.  It does
162    not support the <em>Username Lookup</em> mode at all, at this point.</p>
163
164  </blockquote></td></tr></table>
165
166
167  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Administrator Login Mode Functionality"><strong>Administrator Login Mode Functionality</strong></a></font></td></tr><tr><td><blockquote>
168
169
170    <h3>Configurable Properties</h3>
171
172    <p>The implementation shall support the following properties
173    that can be configured with JavaBeans property setters:</p>
174    <ul>
175    <li><code>connectionURL</code> - URL of the directory server we will
176        be contacting.</li>
177    <li><code>contextFactory</code> - Fully qualified class name of the JNDI
178        context factory used to retrieve our InitialContext.
179        [com.sun.jndi.ldap.LdapCtxFactory]</li>
180    <li>Additional configuration properties required to establish the
181        appropriate connection.  [Requested]</li>
182    <li>Connection pool configuration properties.  [Requested]</li>
183    <li>Configuration properties defining how a particular user is
184        authenticated.  The following capabilities should be supported:
185        <ul>
186        <li>Substitute the specified username into a string.  [Requested]</li>
187        <li>Retrieve the distinguished name (DN) of an authorized user via an
188            LDAP search string with a replacement placeholder for the
189            username, and comparison of the password to a configurable
190            attribute retrieved from the search result.  [Current]</li>
191        </ul></li>
192    <li>Configuration properties defining how the roles associated with a
193        particular authenticated user can be retrieved.  The following
194        approaches should be supported:
195        <ul>
196        <li>Retrieve a specified attribute (possibly multi-valued)
197            from an LDAP search expression,
198            with a replacement placeholder for the DN of the user.
199            [Current]</li>
200        <li>Retrieve a set of role names that are defined implicitly (by
201            selecting principals that match a search pattern) rather than
202            explicitly (by finding a particular attribute value).
203            [Requested]</li>
204        </ul></li>
205    </ul>
206
207    <h3>Lifecycle Functionality</h3>
208
209    <p>The following processing must be performed when the <code>start()</code>
210    method is called:</p>
211    <ul>
212    <li>Establish a connection to the configured directory server, using the
213        configured system administrator username and password.  [Current]</li>
214    <li>Configure and establish a connection pool of connections to the
215        directory server.  [Requested]</li>
216    </ul>
217
218    <p>The following processing must be performed when the <code>stop()</code>
219    method is called:</p>
220    <ul>
221    <li>Close any opened connections to the directory server.</li>
222    </ul>
223
224
225    <h3>Method authenticate() Functionality</h3>
226
227    <p>When <code>authenticate()</code> is called, the following processing
228    is required:</p>
229    <ul>
230    <li>Acquire the one and only connection [Current] or acquire a connection
231        from the connection pool [Requested].</li>
232    <li>Authenticate the user by retrieving the user's Distinguished Name,
233        based on the specified username and password.</li>
234    <li>If the user was not authenticated, release the allocated connection
235        and return <code>null</code>.</li>
236    <li>Acquire a <code>List</code> of the security roles assigned to the
237        authenticated user.</li>
238    <li>Construct a new instance of class
239        <code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
240        constructor arguments:  this realm instance, the authenticated
241        username, and a <code>List</code> of the security roles associated
242        with this user.</li>
243    <li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
244        <code>GenericPrincipal</code> objects for a particular user, because
245        the information in the directory server might have changed since the
246        last time this user was authenticated.</li>
247    <li>Return the newly constructed <code>GenericPrincipal</code>.</li>
248    </ul>
249
250
251    <h3>Method hasRole() Functionality</h3>
252
253    <p>When <code>hasRole()</code> is called, the following processing
254    is required:</p>
255    <ul>
256    <li>The <code>principal</code> that is passed as an argument SHOULD
257        be one that we returned (instanceof class
258        <code>org.apache.catalina.realm.GenericPrincipal</code>, with a
259        <code>realm</code> property that is equal to our instance.</li>
260    <li>If the passed <code>principal</code> meets these criteria, check
261        the specified role against the list returned by
262        <code>getRoles()</code>, and return <code>true</code> if the
263        specified role is included; otherwise, return <code>false</code>.</li>
264    <li>If the passed <code>principal</code> does not meet these criteria,
265        return <code>false</code>.</li>
266    </ul>
267
268  </blockquote></td></tr></table>
269
270
271  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Username Login Mode Functionality"><strong>Username Login Mode Functionality</strong></a></font></td></tr><tr><td><blockquote>
272
273    <h3>Configurable Properties</h3>
274
275    <p>The implementation shall support the following properties
276    that can be configured with JavaBeans property setters:</p>
277    <ul>
278    <li><code>connectionURL</code> - URL of the directory server we will
279        be contacting.</li>
280    <li><code>contextFactory</code> - Fully qualified class name of the JNDI
281        context factory used to retrieve our InitialContext.
282        [com.sun.jndi.ldap.LdapCtxFactory]</li>
283    <li>Additional configuration properties required to establish the
284        appropriate connection.  [Requested]</li>
285    <li>Connection pool configuration properties.  [Requested]</li>
286    <li>Configuration properties defining if and how a user might be looked
287        up before binding to the directory server.  The following approaches
288        should be supported:
289        <ul>
290        <li>No previous lookup is required - username specified by the user
291            is the same as that used to authenticate to the directory
292            server.</li>
293        <li>Substitute the specified username into a string.</li>
294        <li>Search the directory server based on configured criteria to
295            retrieve the distinguished name of the user, then attempt to
296            bind with that distinguished name.</li>
297        </ul></li>
298    <li>Configuration properties defining how the roles associated with a
299        particular authenticated user can be retrieved.  The following
300        approaches should be supported:
301        <ul>
302        <li>Retrieve a specified attribute (possibly multi-valued)
303            from an LDAP search expression,
304            with a replacement placeholder for the DN of the user.
305            [Current]</li>
306        </ul></li>
307    </ul>
308
309    <h3>Lifecycle Functionality</h3>
310
311    <p>The following processing must be performed when the <code>start()</code>
312    method is called:</p>
313    <ul>
314    <li>None required.</li>
315    </ul>
316
317    <p>The following processing must be performed when the <code>stop()</code>
318    method is called:</p>
319    <ul>
320    <li>None required.</li>
321    </ul>
322
323
324    <h3>Method authenticate() Functionality</h3>
325
326    <p>When <code>authenticate()</code> is called, the following processing
327    is required:</p>
328    <ul>
329    <li>Attempt to bind to the directory server, using the username and
330        password provided by the user.</li>
331    <li>If the user was not authenticated, release the allocated connection
332        and return <code>null</code>.</li>
333    <li>Acquire a <code>List</code> of the security roles assigned to the
334        authenticated user.</li>
335    <li>Construct a new instance of class
336        <code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
337        constructor arguments:  this realm instance, the authenticated
338        username, and a <code>List</code> of the security roles associated
339        with this user.</li>
340    <li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
341        <code>GenericPrincipal</code> objects for a particular user, because
342        the information in the directory server might have changed since the
343        last time this user was authenticated.</li>
344    <li>Return the newly constructed <code>GenericPrincipal</code>.</li>
345    </ul>
346
347
348    <h3>Method hasRole() Functionality</h3>
349
350    <p>When <code>hasRole()</code> is called, the following processing
351    is required:</p>
352    <ul>
353    <li>The <code>principal</code> that is passed as an argument SHOULD
354        be one that we returned (instanceof class
355        <code>org.apache.catalina.realm.GenericPrincipal</code>, with a
356        <code>realm</code> property that is equal to our instance.</li>
357    <li>If the passed <code>principal</code> meets these criteria, check
358        the specified role against the list returned by
359        <code>getRoles()</code>, and return <code>true</code> if the
360        specified role is included; otherwise, return <code>false</code>.</li>
361    <li>If the passed <code>principal</code> does not meet these criteria,
362        return <code>false</code>.</li>
363    </ul>
364
365  </blockquote></td></tr></table>
366
367</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Testable Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote>
368
369  <p>In addition the the assertions implied by the functionality requirements
370  listed above, the following additional assertions shall be tested to
371  validate the behavior of <code>JNDIRealm</code>:</p>
372  <ul>
373  </ul>
374
375</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
376        Copyright &copy; 1999-2008, Apache Software Foundation
377        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.