| <?xml version="1.0"?> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="fs-memory-realm.html"> |
| |
| &project; |
| |
| <properties> |
| <author email="craigmcc@apache.org">Craig McClanahan</author> |
| <title>MemoryRealm</title> |
| <revision>$Id$</revision> |
| </properties> |
| |
| <body> |
| |
| |
| <section name="Overview"> |
| |
| |
| <subsection name="Introduction"> |
| |
| <p>The purpose of the <strong>MemoryRealm</strong> implementation is to |
| provide a mechanism by which Tomcat 5 can acquire information needed |
| to authenticate web application users, and define their security roles, |
| from a simple text-based configuration file in XML format. This is |
| intended to simplify the initial installation and operation of Tomcat 5, |
| without the complexity of configuring a database or directory server |
| based Realm. It is not intended for production use.</p> |
| |
| <p>This specification reflects a combination of functionality that is |
| already present in the <code>org.apache.catalina.realm.MemoryRealm</code> |
| class, as well as requirements for enhancements that have been |
| discussed. Where appropriate, requirements statements are marked |
| <em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p> |
| |
| <p>The current status of this functional specification is |
| <strong>PROPOSED</strong>. It has not yet been discussed and |
| agreed to on the TOMCAT-DEV mailing list.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="External Specifications"> |
| |
| <p>The implementation of this functionality depends on the following |
| external specifications:</p> |
| <ul> |
| <li>None</li> |
| </ul> |
| |
| </subsection> |
| |
| |
| <subsection name="Implementation Requirements"> |
| |
| <p>The implementation of this functionality shall conform to the |
| following requirements:</p> |
| <ul> |
| <li>Be realized in one or more implementation classes.</li> |
| <li>Implement the <code>org.apache.catalina.Realm</code> interface. |
| [Current]</li> |
| <li>Implement the <code>org.apache.catalina.Lifecycle</code> |
| interface. [Current]</li> |
| <li>Subclass the <code>org.apache.catalina.realm.RealmBase</code> |
| base class.</li> |
| <li>Live in the <code>org.apache.catalina.realm</code> package. |
| [Current]</li> |
| <li>Support a configurable debugging detail level. [Current]</li> |
| <li>Log debugging and operational messages (suitably internationalized) |
| via the <code>getContainer().log()</code> method. [Current]</li> |
| </ul> |
| |
| </subsection> |
| |
| |
| </section> |
| |
| |
| <section name="Dependencies"> |
| |
| |
| <subsection name="Environmental Dependencies"> |
| |
| <p>The following environmental dependencies must be met in order for |
| MemoryRealm to operate correctly:</p> |
| <ul> |
| <li>The desire to utilize MemoryRealm must be registered in |
| <code>$CATALINA_HOME/conf/server.xml</code>, in a |
| <code><Realm></code> element that is nested inside a |
| corresponding <code><Engine></code>, <code><Host></code>, |
| or <code><Context></code> element. (This is already |
| included in the default <code>server.xml</code> file.)</li> |
| </ul> |
| |
| </subsection> |
| |
| |
| <subsection name="Container Dependencies"> |
| |
| <p>Correct operation of MemoryRealm depends on the following |
| specific features of the surrounding container:</p> |
| <ul> |
| <li>Interactions with <code>MemoryRealm</code> will be initiated by |
| the appropriate <code>Authenticator</code> implementation, based |
| on the login method that is selected.</li> |
| <li><code>MemoryRealm</code> must have an XML parser compatible with |
| the JAXP/1.1 APIs available to it. This is normally accomplished |
| by placing the corresponding JAR files in directory |
| <code>$CATALINA_HOME/server/lib</code> (to make them visible only |
| to internal Catalina classes) or in directory |
| <code>$CATALINA_HOME/common/lib</code> (to make them visible to |
| Catalina internal classes <strong>and</strong> installed web |
| applications).</li> |
| </ul> |
| |
| </subsection> |
| |
| |
| </section> |
| |
| |
| <section name="Functionality"> |
| |
| |
| <subsection name="Overview of Operation"> |
| |
| <p>The main purpose of <code>MemoryRealm</code> is to allow Catalina to |
| authenticate users, and look up the corresponding security roles, from |
| the information found in an XML-format configuration file. The format |
| of this file is described below. When a <code>MemoryRealm</code> |
| instance is started, it will read the contents of this XML file and create |
| an "in memory database" of all the valid users and their associated |
| security roles.</p> |
| |
| <p>Each time that Catalina needs to authenticate a user, it will call |
| the <code>authenticate()</code> method of this Realm implementation, |
| passing the username and password that were specified by the user. If |
| we find the user in the database (and match on the password), we accumulate |
| all of the security roles that are defined for this user, and create a |
| new <code>GenericPrincipal</code> object to be returned. If the user |
| is not authenticated, we return <code>null</code> instead. The |
| <code>GenericUser</code> object caches the set of security roles that |
| were owned by this user at the time of authentication, so that calls to |
| <code>isUserInRole()</code> can be answered without going back to the |
| database every time.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="Detailed Functional Requirements"> |
| |
| |
| <h3>Configurable Properties</h3> |
| |
| <p>The implementation shall support the following properties |
| that can be configured with JavaBeans property setters:</p> |
| <ul> |
| <li>Configurable debugging detail level.</li> |
| <li>Configurable file pathname (absolute or relative to |
| <code>$CATALINA_HOME</code> of the XML file containing our |
| defined users. [<code>conf/tomcat-users.xml</code>].</li> |
| </ul> |
| |
| <h3>Lifecycle Functionality</h3> |
| |
| <p>The following processing must be performed when the <code>start()</code> |
| method is called:</p> |
| <ul> |
| <li>Open and parse the specified XML file.</li> |
| <li>Create an in-memory database representation of the XML file |
| contents.</li> |
| <li><strong>NOTE</strong> - There is no requirement to recognize |
| subsequent changes to the contents of the XML file.</li> |
| </ul> |
| |
| <p>The following processing must be performed when the <code>stop()</code> |
| method is called:</p> |
| <ul> |
| <li>Release object references to the in-memory database representation.</li> |
| </ul> |
| |
| |
| <h3>Method authenticate() Functionality</h3> |
| |
| <p>When <code>authenticate()</code> is called, the following processing |
| is required:</p> |
| <ul> |
| <li>Select the one and only "user" instance from the in-memory database, |
| based on matching the specified username. If there is no such |
| instance, return <code>null</code>.</li> |
| <li>Authenticate the user by comparing the (possibly encrypted) password |
| value that was received against the password presented by the user. |
| If there is no match, return <code>null</code>.</li> |
| <li>Construct a new instance of class |
| <code>org.apache.catalina.realm.GenericPrincipal</code> (if not |
| already using this as the internal database representation) that |
| contains the authenticated username and a <code>List</code> of the |
| security roles associated with this user.</li> |
| <li>Return the newly constructed <code>GenericPrincipal</code>.</li> |
| </ul> |
| |
| |
| <h3>Method hasRole() Functionality</h3> |
| |
| <p>When <code>hasRole()</code> is called, the following processing |
| is required:</p> |
| <ul> |
| <li>The <code>principal</code> that is passed as an argument SHOULD |
| be one that we returned (instanceof class |
| <code>org.apache.catalina.realm.GenericPrincipal</code>, with a |
| <code>realm</code> property that is equal to our instance.</li> |
| <li>If the passed <code>principal</code> meets these criteria, check |
| the specified role against the list returned by |
| <code>getRoles()</code>, and return <code>true</code> if the |
| specified role is included; otherwise, return <code>false</code>.</li> |
| <li>If the passed <code>principal</code> does not meet these criteria, |
| return <code>false</code>.</li> |
| </ul> |
| |
| </subsection> |
| |
| </section> |
| |
| |
| <section name="Testable Assertions"> |
| |
| <p>In addition the the assertions implied by the functionality requirements |
| listed above, the following additional assertions shall be tested to |
| validate the behavior of <code>MemoryRealm</code>:</p> |
| <ul> |
| </ul> |
| |
| </section> |
| |
| |
| </body> |
| |
| </document> |
