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

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

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