tomcat-uid/webapps/docs/funcspecs/fs-jdbc-realm.html - UniIdentify/tomcat - Gitiles

 <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications (7.0.77) - JDBCRealm</title><meta name="author" content="Craig McClanahan"><style type="text/css" media="print">
     .noPrint {display: none;}
     td#mainBody {width: 100%;}
 </style><style type="text/css">
 code {background-color:rgb(224,255,255);padding:0 0.1em;}
 code.attributeName, code.propertyName {background-color:transparent;}


 table {
   border-collapse: collapse;
   text-align: left;
 }
 table *:not(table) {
   /* Prevent border-collapsing for table child elements like <div> */
   border-collapse: separate;
 }

 th {
   text-align: left;
 }


 div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
   background-color: transparent;
 }
 div.codeBox {
   overflow: auto;
   margin: 1em 0;
 }
 div.codeBox pre {
   margin: 0;
   padding: 4px;
   border: 1px solid #999;
   border-radius: 5px;
   background-color: #eff8ff;
   display: table; /* To prevent <pre>s from taking the complete available width. */
   /*
   When it is officially supported, use the following CSS instead of display: table
   to prevent big <pre>s from exceeding the browser window:
   max-width: available;
   width: min-content;
   */
 }

 div.codeBox pre.wrap {
   white-space: pre-wrap;
 }


 table.defaultTable tr, table.detail-table tr {
     border: 1px solid #CCC;
 }

 table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
     background-color: #FAFBFF;
 }

 table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
     background-color: #EEEFFF;
 }

 table.defaultTable th, table.detail-table th {
   background-color: #88b;
   color: #fff;
 }

 table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
   padding: 5px 8px;
 }


 p.notice {
     border: 1px solid rgb(255, 0, 0);
     background-color: rgb(238, 238, 238);
     color: rgb(0, 51, 102);
     padding: 0.5em;
     margin: 1em 2em 1em 1em;
 }
 </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="
       Catalina Functional Specifications
     " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" 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><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</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></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>JDBCRealm</h1><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>
 <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>
 </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="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>

     <p>The purpose of the <strong>JDBCRealm</strong> implementation is to
     provide a mechanism by which Tomcat can acquire information needed
     to authenticate web application users, and define their security roles,
     from a relational database accessed via JDBC APIs.  For integration
     with Catalina, the resulting class(es) must implement the
     <code>org.apache.catalina.Realm</code> interface.</p>

     <p>This specification reflects a combination of functionality that is
     already present in the <code>org.apache.catalina.realm.JDBCRealm</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>

   </blockquote></td></tr></table>


   <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>

     <p>The implementation of this functionality depends on the following
     external specifications:</p>
     <ul>
     <li><a href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html">
         Java Database Connectivity</a> (version 2.0 or later)</li>
     <li><a href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html">
         Java Database Connectivity Optional Package</a> (version 2.0 or later)</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="Implementation Requirements"><!--()--></a><a name="Implementation_Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote>

     <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>

   </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="Dependencies"><strong>Dependencies</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="Environmental Dependencies"><!--()--></a><a name="Environmental_Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote>

     <p>The following environmental dependencies must be met in order for
     JDBCRealm to operate correctly:</p>
     <ul>
     <li>The desire to utilize JDBCRealm must be registered in
         <code>$CATALINA_BASE/conf/server.xml</code>, in a
         <code>&lt;Realm&gt;</code> element that is nested inside a
         corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
         or <code>&lt;Context&gt;</code> element.</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="Container Dependencies"><!--()--></a><a name="Container_Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>

     <p>Correct operation of JDBCRealm depends on the following
     specific features of the surrounding container:</p>
     <ul>
     <li>Interactions with <code>JDBCRealm</code> will be initiated by
         the appropriate <code>Authenticator</code> implementation, based
         on the login method that is selected.</li>
     <li><code>JDBCRealm</code> must have the JDBC standard API classes
         available to it.  For a JDK 1.2 or later container, these APIs
         are included in the standard platform.</li>
     <li>When connection pooling is implemented, <code>JDBCRealm</code>
         must have the JDBC Optional Package (version 2.0 or later) APIs
         available to it.  This library is available as a separate
         download (and will be included in Tomcat binary distributions).</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="Functionality"><strong>Functionality</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="Overview of Operation"><!--()--></a><a name="Overview_of_Operation"><strong>Overview of Operation</strong></a></font></td></tr><tr><td><blockquote>

     <p>The main purpose of <code>JDBCRealm</code> is to allow Catalina to
     authenticate users, and look up the corresponding security roles, from
     the information found in a relational database accessed via JDBC APIs.
     For maximum flexibility, the details of how this is done (for example,
     the names of the required tables and columns) should be configurable.</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>

   </blockquote></td></tr></table>


   <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>


     <h3>Configurable Properties</h3>

     <p>The implementation shall support the following properties
     that can be configured with JavaBeans property setters:</p>
     <ul>
     <li>Configuration parameters defining the JDBC driver to use, the
         database connection URL to be accessed, and the username/password
         to use for logging in. [Current]</li>
     <li>Configuration parameters describing the connection pool to be
         created to support simultaneous authentications. [Requested]</li>
     <li>Name of the tables to be searched for users and roles. [Current]</li>
     <li>Name of the columns to be used for usernames, passwords, and
         role names.  [Current]</li>
     </ul>

     <h3>Lifecycle Functionality</h3>

     <p>The following processing must be performed when the <code>start()</code>
     method is called:</p>
     <ul>
     <li>Establish a connection to the configured database, using the
         configured username and password.  [Current]</li>
     <li>Configure and establish a connection pool of connections to the
         database.  [Requested]</li>
     </ul>

     <p>The following processing must be performed when the <code>stop()</code>
     method is called:</p>
     <ul>
     <li>Close any opened connections to the database.</li>
     </ul>


     <h3>Method authenticate() Functionality</h3>

     <p>When <code>authenticate()</code> is called, the following processing
     is required:</p>
     <ul>
     <li>Acquire the one and only connection [Current] or acquire a connection
         from the connection pool [Requested].</li>
     <li>Select the one and only row from the user's table for this user,
         and retrieve the corresponding password column.  If zero rows (or
         more than one row) are found, 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>Acquire a <code>List</code> of the security roles assigned to the
         authenticated user by selecting from the roles table.</li>
     <li>Construct a new instance of class
         <code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
         constructor arguments:  this realm instance, the authenticated
         username, and a <code>List</code> of the security roles associated
         with this user.</li>
     <li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
         <code>GenericPrincipal</code> objects for a particular user, because
         the information in the directory server might have changed since the
         last time this user was authenticated.</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>

   </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="Testable Assertions"><!--()--></a><a name="Testable_Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote>

   <p>In addition to the assertions implied by the functionality requirements
   listed above, the following additional assertions shall be tested to
   validate the behavior of <code>JDBCRealm</code>:</p>
   <ul>
   </ul>

 </blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
               on improving documentation for Apache Tomcat.<br><br>
               If you have trouble and need help, read
               <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
               and ask your question on the tomcat-users
               <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
               Do not ask such questions here. This is not a Q&amp;A section.<br><br>
               The Apache Comments System is explained <a href="../comments.html">here</a>.
               Comments may be removed by our moderators if they are either
               implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
               var comments_shortname = 'tomcat';
               var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/funcspecs/fs-jdbc-realm.html';
               (function(w, d) {
                   if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
                       d.write('<div id="comments_thread"><\/div>');
                       var s = d.createElement('script');
                       s.type = 'text/javascript';
                       s.async = true;
                       s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
                       (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
                   }
                   else {
                       d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
                   }
               })(window, document);
               //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
         Copyright &copy; 1999-2017, Apache Software Foundation
         </em></font></div></td></tr></table></body></html>
	<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications (7.0.77) - JDBCRealm</title><meta name="author" content="Craig McClanahan"><style type="text/css" media="print">
	.noPrint {display: none;}
	td#mainBody {width: 100%;}
	</style><style type="text/css">
	code {background-color:rgb(224,255,255);padding:0 0.1em;}
	code.attributeName, code.propertyName {background-color:transparent;}


	table {
	border-collapse: collapse;
	text-align: left;
	}
	table *:not(table) {
	/* Prevent border-collapsing for table child elements like <div> */
	border-collapse: separate;
	}

	th {
	text-align: left;
	}


	div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
	background-color: transparent;
	}
	div.codeBox {
	overflow: auto;
	margin: 1em 0;
	}
	div.codeBox pre {
	margin: 0;
	padding: 4px;
	border: 1px solid #999;
	border-radius: 5px;
	background-color: #eff8ff;
	display: table; /* To prevent <pre>s from taking the complete available width. */
	/*
	When it is officially supported, use the following CSS instead of display: table
	to prevent big <pre>s from exceeding the browser window:
	max-width: available;
	width: min-content;
	*/
	}

	div.codeBox pre.wrap {
	white-space: pre-wrap;
	}


	table.defaultTable tr, table.detail-table tr {
	border: 1px solid #CCC;
	}

	table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
	background-color: #FAFBFF;
	}

	table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
	background-color: #EEEFFF;
	}

	table.defaultTable th, table.detail-table th {
	background-color: #88b;
	color: #fff;
	}

	table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
	padding: 5px 8px;
	}


	p.notice {
	border: 1px solid rgb(255, 0, 0);
	background-color: rgb(238, 238, 238);
	color: rgb(0, 51, 102);
	padding: 0.5em;
	margin: 1em 2em 1em 1em;
	}
	</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="
	Catalina Functional Specifications
	" border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" 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><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</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></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>JDBCRealm</h1><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>
	<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>
	</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="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>

	<p>The purpose of the <strong>JDBCRealm</strong> implementation is to
	provide a mechanism by which Tomcat can acquire information needed
	to authenticate web application users, and define their security roles,
	from a relational database accessed via JDBC APIs. For integration
	with Catalina, the resulting class(es) must implement the
	<code>org.apache.catalina.Realm</code> interface.</p>

	<p>This specification reflects a combination of functionality that is
	already present in the <code>org.apache.catalina.realm.JDBCRealm</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>

	</blockquote></td></tr></table>


	<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>

	<p>The implementation of this functionality depends on the following
	external specifications:</p>
	<ul>
	<li><a href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html">
	Java Database Connectivity</a> (version 2.0 or later)</li>
	<li><a href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html">
	Java Database Connectivity Optional Package</a> (version 2.0 or later)</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="Implementation Requirements"><!--()--></a><a name="Implementation_Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote>

	<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>

	</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="Dependencies"><strong>Dependencies</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="Environmental Dependencies"><!--()--></a><a name="Environmental_Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote>

	<p>The following environmental dependencies must be met in order for
	JDBCRealm to operate correctly:</p>
	<ul>
	<li>The desire to utilize JDBCRealm must be registered in
	<code>$CATALINA_BASE/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.</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="Container Dependencies"><!--()--></a><a name="Container_Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>

	<p>Correct operation of JDBCRealm depends on the following
	specific features of the surrounding container:</p>
	<ul>
	<li>Interactions with <code>JDBCRealm</code> will be initiated by
	the appropriate <code>Authenticator</code> implementation, based
	on the login method that is selected.</li>
	<li><code>JDBCRealm</code> must have the JDBC standard API classes
	available to it. For a JDK 1.2 or later container, these APIs
	are included in the standard platform.</li>
	<li>When connection pooling is implemented, <code>JDBCRealm</code>
	must have the JDBC Optional Package (version 2.0 or later) APIs
	available to it. This library is available as a separate
	download (and will be included in Tomcat binary distributions).</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="Functionality"><strong>Functionality</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="Overview of Operation"><!--()--></a><a name="Overview_of_Operation"><strong>Overview of Operation</strong></a></font></td></tr><tr><td><blockquote>

	<p>The main purpose of <code>JDBCRealm</code> is to allow Catalina to
	authenticate users, and look up the corresponding security roles, from
	the information found in a relational database accessed via JDBC APIs.
	For maximum flexibility, the details of how this is done (for example,
	the names of the required tables and columns) should be configurable.</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>

	</blockquote></td></tr></table>


	<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>


	<h3>Configurable Properties</h3>

	<p>The implementation shall support the following properties
	that can be configured with JavaBeans property setters:</p>
	<ul>
	<li>Configuration parameters defining the JDBC driver to use, the
	database connection URL to be accessed, and the username/password
	to use for logging in. [Current]</li>
	<li>Configuration parameters describing the connection pool to be
	created to support simultaneous authentications. [Requested]</li>
	<li>Name of the tables to be searched for users and roles. [Current]</li>
	<li>Name of the columns to be used for usernames, passwords, and
	role names. [Current]</li>
	</ul>

	<h3>Lifecycle Functionality</h3>

	<p>The following processing must be performed when the <code>start()</code>
	method is called:</p>
	<ul>
	<li>Establish a connection to the configured database, using the
	configured username and password. [Current]</li>
	<li>Configure and establish a connection pool of connections to the
	database. [Requested]</li>
	</ul>

	<p>The following processing must be performed when the <code>stop()</code>
	method is called:</p>
	<ul>
	<li>Close any opened connections to the database.</li>
	</ul>


	<h3>Method authenticate() Functionality</h3>

	<p>When <code>authenticate()</code> is called, the following processing
	is required:</p>
	<ul>
	<li>Acquire the one and only connection [Current] or acquire a connection
	from the connection pool [Requested].</li>
	<li>Select the one and only row from the user's table for this user,
	and retrieve the corresponding password column. If zero rows (or
	more than one row) are found, 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>Acquire a <code>List</code> of the security roles assigned to the
	authenticated user by selecting from the roles table.</li>
	<li>Construct a new instance of class
	<code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
	constructor arguments: this realm instance, the authenticated
	username, and a <code>List</code> of the security roles associated
	with this user.</li>
	<li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
	<code>GenericPrincipal</code> objects for a particular user, because
	the information in the directory server might have changed since the
	last time this user was authenticated.</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>

	</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="Testable Assertions"><!--()--></a><a name="Testable_Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote>

	<p>In addition to the assertions implied by the functionality requirements
	listed above, the following additional assertions shall be tested to
	validate the behavior of <code>JDBCRealm</code>:</p>
	<ul>
	</ul>

	</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
	on improving documentation for Apache Tomcat.<br><br>
	If you have trouble and need help, read
	<a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
	and ask your question on the tomcat-users
	<a href="http://tomcat.apache.org/lists.html">mailing list</a>.
	Do not ask such questions here. This is not a Q&A section.<br><br>
	The Apache Comments System is explained <a href="../comments.html">here</a>.
	Comments may be removed by our moderators if they are either
	implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
	var comments_shortname = 'tomcat';
	var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/funcspecs/fs-jdbc-realm.html';
	(function(w, d) {
	if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
	d.write('<div id="comments_thread"><\/div>');
	var s = d.createElement('script');
	s.type = 'text/javascript';
	s.async = true;
	s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
	(d.getElementsByTagName('head')[0] \|\| d.getElementsByTagName('body')[0]).appendChild(s);
	}
	else {
	d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
	}
	})(window, document);
	//--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
	Copyright © 1999-2017, Apache Software Foundation
	</em></font></div></td></tr></table></body></html>