Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / fd5ee81fec460cbe9ad65f300b0faf1bf03c19bc / . / tomcat-uidm / webapps / docs / funcspecs / fs-jdbc-realm.html
blob: b2c48443a5572150048d460757b1d9ebdb1d4ec4 [file] [log] [blame]
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications (6.0.39) - JDBCRealm</title><meta name="author" content="Craig McClanahan"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
5 Catalina Functional Specifications
6 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.39, Jan 27 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="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 width="80%" valign="top" align="left" id="mainBody"><h1>Catalina Functional Specifications</h1><h2>JDBCRealm</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
7<ul><li><a href="#Overview">Overview</a><ol><li><a href="#Introduction">Introduction</a></li><li><a href="#External_Specifications">External Specifications</a></li><li><a href="#Implementation_Requirements">Implementation Requirements</a></li></ol></li><li><a href="#Dependencies">Dependencies</a><ol><li><a href="#Environmental_Dependencies">Environmental Dependencies</a></li><li><a href="#Container_Dependencies">Container Dependencies</a></li></ol></li><li><a href="#Functionality">Functionality</a><ol><li><a href="#Overview_of_Operation">Overview of Operation</a></li><li><a href="#Detailed_Functional_Requirements">Detailed Functional Requirements</a></li></ol></li><li><a href="#Testable_Assertions">Testable Assertions</a></li></ul>
8</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>
9
10
11 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
12
13 <p>The purpose of the <strong>JDBCRealm</strong> implementation is to
14 provide a mechanism by which Tomcat 6 can acquire information needed
15 to authenticate web application users, and define their security roles,
16 from a relational database accessed via JDBC APIs. For integration
17 with Catalina, the resulting class(es) must implement the
18 <code>org.apache.catalina.Realm</code> interface.</p>
19
20 <p>This specification reflects a combination of functionality that is
21 already present in the <code>org.apache.catalina.realm.JDBCRealm</code>
22 class, as well as requirements for enhancements that have been
23 discussed. Where appropriate, requirements statements are marked
24 <em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>
25
26 <p>The current status of this functional specification is
27 <strong>PROPOSED</strong>. It has not yet been discussed and
28 agreed to on the TOMCAT-DEV mailing list.</p>
29
30 </blockquote></td></tr></table>
31
32
33 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="External Specifications"><!--()--></a><a name="External_Specifications"><strong>External Specifications</strong></a></font></td></tr><tr><td><blockquote>
34
35 <p>The implementation of this functionality depends on the following
36 external specifications:</p>
37 <ul>
38 <li><a href="http://java.sun.com/products/jdbc/">Java Database
39 Connectivity</a> (version 2.0 or later)</li>
40 <li><a href="http://java.sun.com/products/jdbc/">Java Database
41 Connectivity Optional Package</a> (version 2.0 or later)</li>
42 </ul>
43
44 </blockquote></td></tr></table>
45
46
47 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Implementation Requirements"><!--()--></a><a name="Implementation_Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote>
48
49 <p>The implementation of this functionality shall conform to the
50 following requirements:</p>
51 <ul>
52 <li>Be realized in one or more implementation classes.</li>
53 <li>Implement the <code>org.apache.catalina.Realm</code> interface.
54 [Current]</li>
55 <li>Implement the <code>org.apache.catalina.Lifecycle</code>
56 interface. [Current]</li>
57 <li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
58 base class.</li>
59 <li>Live in the <code>org.apache.catalina.realm</code> package.
60 [Current]</li>
61 <li>Support a configurable debugging detail level. [Current]</li>
62 <li>Log debugging and operational messages (suitably internationalized)
63 via the <code>getContainer().log()</code> method. [Current]</li>
64 </ul>
65
66 </blockquote></td></tr></table>
67
68
69</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote>
70
71
72 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Environmental Dependencies"><!--()--></a><a name="Environmental_Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote>
73
74 <p>The following environmental dependencies must be met in order for
75 JDBCRealm to operate correctly:</p>
76 <ul>
77 <li>The desire to utilize JDBCRealm must be registered in
78 <code>$CATALINA_BASE/conf/server.xml</code>, in a
79 <code>&lt;Realm&gt;</code> element that is nested inside a
80 corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
81 or <code>&lt;Context&gt;</code> element.</li>
82 </ul>
83
84 </blockquote></td></tr></table>
85
86
87 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Container Dependencies"><!--()--></a><a name="Container_Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>
88
89 <p>Correct operation of JDBCRealm depends on the following
90 specific features of the surrounding container:</p>
91 <ul>
92 <li>Interactions with <code>JDBCRealm</code> will be initiated by
93 the appropriate <code>Authenticator</code> implementation, based
94 on the login method that is selected.</li>
95 <li><code>JDBCRealm</code> must have the JDBC standard API classes
96 available to it. For a JDK 1.2 or later container, these APIs
97 are included in the standard platform.</li>
98 <li>When connection pooling is implemented, <code>JDBCRealm</code>
99 must have the JDBC Optional Package (version 2.0 or later) APIs
100 available to it. This library is available as a separate
101 download (and will be included in Tomcat binary distributions).</li>
102 </ul>
103
104 </blockquote></td></tr></table>
105
106
107</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote>
108
109
110 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Overview of Operation"><!--()--></a><a name="Overview_of_Operation"><strong>Overview of Operation</strong></a></font></td></tr><tr><td><blockquote>
111
112 <p>The main purpose of <code>JDBCRealm</code> is to allow Catalina to
113 authenticate users, and look up the corresponding security roles, from
114 the information found in a relational database accessed via JDBC APIs.
115 For maximum flexibility, the details of how this is done (for example,
116 the names of the required tables and columns) should be configurable.</p>
117
118 <p>Each time that Catalina needs to authenticate a user, it will call
119 the <code>authenticate()</code> method of this Realm implementation,
120 passing the username and password that were specified by the user. If
121 we find the user in the database (and match on the password), we accumulate
122 all of the security roles that are defined for this user, and create a
123 new <code>GenericPrincipal</code> object to be returned. If the user
124 is not authenticated, we return <code>null</code> instead. The
125 <code>GenericUser</code> object caches the set of security roles that
126 were owned by this user at the time of authentication, so that calls to
127 <code>isUserInRole()</code> can be answered without going back to the
128 database every time.</p>
129
130 </blockquote></td></tr></table>
131
132
133 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Detailed Functional Requirements"><!--()--></a><a name="Detailed_Functional_Requirements"><strong>Detailed Functional Requirements</strong></a></font></td></tr><tr><td><blockquote>
134
135
136 <h3>Configurable Properties</h3>
137
138 <p>The implementation shall support the following properties
139 that can be configured with JavaBeans property setters:</p>
140 <ul>
141 <li>Configuration parameters defining the JDBC driver to use, the
142 database connection URL to be accessed, and the username/password
143 to use for logging in. [Current]</li>
144 <li>Configuration parameters describing the connection pool to be
145 created to support simultaneous authentications. [Requested]</li>
146 <li>Name of the tables to be searched for users and roles. [Current]</li>
147 <li>Name of the columns to be used for usernames, passwords, and
148 role names. [Current]</li>
149 </ul>
150
151 <h3>Lifecycle Functionality</h3>
152
153 <p>The following processing must be performed when the <code>start()</code>
154 method is called:</p>
155 <ul>
156 <li>Establish a connection to the configured database, using the
157 configured username and password. [Current]</li>
158 <li>Configure and establish a connection pool of connections to the
159 database. [Requested]</li>
160 </ul>
161
162 <p>The following processing must be performed when the <code>stop()</code>
163 method is called:</p>
164 <ul>
165 <li>Close any opened connections to the database.</li>
166 </ul>
167
168
169 <h3>Method authenticate() Functionality</h3>
170
171 <p>When <code>authenticate()</code> is called, the following processing
172 is required:</p>
173 <ul>
174 <li>Acquire the one and only connection [Current] or acquire a connection
175 from the connection pool [Requested].</li>
176 <li>Select the one and only row from the user's table for this user,
177 and retrieve the corresponding password column. If zero rows (or
178 more than one row) are found, return <code>null</code>.</li>
179 <li>Authenticate the user by comparing the (possibly encrypted) password
180 value that was received against the password presented by the user.
181 If there is no match, return <code>null</code>.</li>
182 <li>Acquire a <code>List</code> of the security roles assigned to the
183 authenticated user by selecting from the roles table.</li>
184 <li>Construct a new instance of class
185 <code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
186 constructor arguments: this realm instance, the authenticated
187 username, and a <code>List</code> of the security roles associated
188 with this user.</li>
189 <li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
190 <code>GenericPrincipal</code> objects for a particular user, because
191 the information in the directory server might have changed since the
192 last time this user was authenticated.</li>
193 <li>Return the newly constructed <code>GenericPrincipal</code>.</li>
194 </ul>
195
196
197 <h3>Method hasRole() Functionality</h3>
198
199 <p>When <code>hasRole()</code> is called, the following processing
200 is required:</p>
201 <ul>
202 <li>The <code>principal</code> that is passed as an argument SHOULD
203 be one that we returned (instanceof class
204 <code>org.apache.catalina.realm.GenericPrincipal</code>, with a
205 <code>realm</code> property that is equal to our instance.</li>
206 <li>If the passed <code>principal</code> meets these criteria, check
207 the specified role against the list returned by
208 <code>getRoles()</code>, and return <code>true</code> if the
209 specified role is included; otherwise, return <code>false</code>.</li>
210 <li>If the passed <code>principal</code> does not meet these criteria,
211 return <code>false</code>.</li>
212 </ul>
213
214 </blockquote></td></tr></table>
215
216</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Testable Assertions"><!--()--></a><a name="Testable_Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote>
217
218 <p>In addition the the assertions implied by the functionality requirements
219 listed above, the following additional assertions shall be tested to
220 validate the behavior of <code>JDBCRealm</code>:</p>
221 <ul>
222 </ul>
223
224</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>
225 Copyright &copy; 1999-2014, Apache Software Foundation
226 </em></font></div></td></tr></table></body></html>