[tomcat] branch 7.0.x updated (e4f402d -> 15bbc3d)

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[tomcat] branch 7.0.x updated (e4f402d -> 15bbc3d)

markt
This is an automated email from the ASF dual-hosted git repository.

markt pushed a change to branch 7.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git.


    from e4f402d  Fix typos
     new 4bac072  Documentation improvements in preparation for deprecating JDBCRealm
     new 15bbc3d  Deprecate JDBCRealm

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 java/org/apache/catalina/mbeans/MBeanFactory.java  |   7 +-
 .../apache/catalina/mbeans/mbeans-descriptors.xml  |   2 +-
 .../org/apache/catalina/realm/DataSourceRealm.java |   2 +-
 java/org/apache/catalina/realm/JDBCRealm.java      |   4 +
 webapps/docs/appdev/deployment.xml                 |   2 +-
 webapps/docs/changelog.xml                         |   3 +
 webapps/docs/config/realm.xml                      | 265 +++++++++++----------
 webapps/docs/host-manager-howto.xml                |   7 +-
 webapps/docs/html-host-manager-howto.xml           |   7 +-
 webapps/docs/realm-howto.xml                       | 228 +++++++++---------
 10 files changed, 269 insertions(+), 258 deletions(-)


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[tomcat] 01/02: Documentation improvements in preparation for deprecating JDBCRealm

markt
This is an automated email from the ASF dual-hosted git repository.

markt pushed a commit to branch 7.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git

commit 4bac072db10ee573d518f84d576ff405621bb446
Author: Mark Thomas <[hidden email]>
AuthorDate: Tue Sep 15 14:32:23 2020 +0100

    Documentation improvements in preparation for deprecating JDBCRealm
---
 webapps/docs/appdev/deployment.xml       |   2 +-
 webapps/docs/config/realm.xml            | 262 +++++++++++++++----------------
 webapps/docs/host-manager-howto.xml      |   7 +-
 webapps/docs/html-host-manager-howto.xml |   7 +-
 webapps/docs/realm-howto.xml             | 225 +++++++++++++-------------
 5 files changed, 249 insertions(+), 254 deletions(-)

diff --git a/webapps/docs/appdev/deployment.xml b/webapps/docs/appdev/deployment.xml
index 6d48a5d..64fef9a 100644
--- a/webapps/docs/appdev/deployment.xml
+++ b/webapps/docs/appdev/deployment.xml
@@ -131,7 +131,7 @@ The location commonly used within a Tomcat installation for shared code is
 <strong>$CATALINA_HOME/lib</strong>. JAR files placed here are visible both to
 web applications and internal Tomcat code. This is a good place to put JDBC
 drivers that are required for both your application or internal Tomcat use
-(such as for a JDBCRealm).</p>
+(such as for a DataSourceRealm).</p>
 
 <p>Out of the box, a standard Tomcat installation includes a variety
 of pre-installed shared library files, including:</p>
diff --git a/webapps/docs/config/realm.xml b/webapps/docs/config/realm.xml
index 5d07c76..b536e13 100644
--- a/webapps/docs/config/realm.xml
+++ b/webapps/docs/config/realm.xml
@@ -92,137 +92,6 @@
   </subsection>
 
 
-  <subsection name="JDBC Database Realm - org.apache.catalina.realm.JDBCRealm">
-
-    <p>The <strong>JDBC Database Realm</strong> connects Tomcat to
-    a relational database, accessed through an appropriate JDBC driver,
-    to perform lookups of usernames, passwords, and their associated
-    roles.  Because the lookup is done each time that it is required,
-    changes to the database will be immediately reflected in the
-    information used to authenticate new logins.</p>
-
-    <p>A rich set of additional attributes lets you configure the required
-    connection to the underlying database, as well as the table and
-    column names used to retrieve the required information:</p>
-
-    <attributes>
-
-      <attribute name="allRolesMode" required="false">
-        <p>This attribute controls how the special role name <code>*</code> is
-        handled when processing authorization constraints in web.xml. By
-        default, the specification compliant value of <code>strict</code> is
-        used which means that the user must be assigned one of the roles defined
-        in web.xml. The alternative values are <code>authOnly</code> which means
-        that the user must be authenticated but no check is made for assigned
-        roles and <code>strictAuthOnly</code> which means that the user must be
-        authenticated and no check will be made for assigned roles unless roles
-        are defined in web.xml in which case the user must be assigned at least
-        one of those roles.</p>
-        <p>When this attribute has the value of <code>authOnly</code> or
-        <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and
-        <strong>userRoleTable</strong> attributes become optional. If those two
-        attributes are omitted, the user's roles will not be loaded by this
-        Realm.</p>
-      </attribute>
-
-      <attribute name="connectionName" required="true">
-        <p>The database username to use when establishing the JDBC
-        connection.</p>
-      </attribute>
-
-      <attribute name="connectionPassword" required="true">
-        <p>The database password to use when establishing the JDBC
-        connection.</p>
-      </attribute>
-
-      <attribute name="connectionURL" required="true">
-        <p>The connection URL to be passed to the JDBC driver when
-        establishing a database connection.</p>
-      </attribute>
-
-      <attribute name="digest" required="false">
-        <p>The name of the <code>MessageDigest</code> algorithm used
-        to encode user passwords stored in the database.  If not specified,
-        user passwords are assumed to be stored in clear-text.</p>
-      </attribute>
-
-      <attribute name="digestEncoding" required="false">
-        <p>The charset for encoding digests.  If not specified, the platform
-        default will be used.</p>
-      </attribute>
-
-      <attribute name="driverName" required="true">
-        <p>Fully qualified Java class name of the JDBC driver to be
-        used to connect to the authentication database.</p>
-      </attribute>
-
-      <attribute name="roleNameCol" required="false">
-        <p>Name of the column, in the "user roles" table, which contains
-        a role name assigned to the corresponding user.</p>
-        <p>This attribute is <strong>required</strong> in majority of
-        configurations. See <strong>allRolesMode</strong> attribute for
-        a rare case when it can be omitted.</p>
-      </attribute>
-
-      <attribute name="stripRealmForGss" required="false">
-        <p>When processing users authenticated via the GSS-API, this attribute
-        controls if any &quot;@...&quot; is removed from the end of the user
-        name. If not specified, the default is <code>true</code>.</p>
-      </attribute>
-
-      <attribute name="transportGuaranteeRedirectStatus" required="false">
-        <p>The HTTP status code to use when the container needs to issue an HTTP
-           redirect to meet the requirements of a configured transport
-           guarantee. The provided status code is not validated. If not
-           specified, the default value of <code>302</code> is used.</p>
-      </attribute>
-
-      <attribute name="userCredCol" required="true">
-        <p>Name of the column, in the "users" table, which contains
-        the user's credentials (i.e. password).  If a value for the
-        <code>digest</code> attribute is specified, this component
-        will assume that the passwords have been encoded with the
-        specified algorithm.  Otherwise, they will be assumed to be
-        in clear text.</p>
-      </attribute>
-
-      <attribute name="userNameCol" required="true">
-        <p>Name of the column, in the "users" and "user roles" table,
-        that contains the user's username.</p>
-      </attribute>
-
-      <attribute name="userRoleTable" required="false">
-        <p>Name of the "user roles" table, which must contain columns
-        named by the <code>userNameCol</code> and <code>roleNameCol</code>
-        attributes.</p>
-        <p>This attribute is <strong>required</strong> in majority of
-        configurations. See <strong>allRolesMode</strong> attribute for
-        a rare case when it can be omitted.</p>
-      </attribute>
-
-      <attribute name="userTable" required="true">
-        <p>Name of the "users" table, which must contain columns named
-        by the <code>userNameCol</code> and <code>userCredCol</code>
-        attributes.</p>
-      </attribute>
-
-      <attribute name="X509UsernameRetrieverClassName" required="false">
-        <p>When using X509 client certificates, this specifies the class name
-        that will be used to retrieve the user name from the certificate.
-        The class must implement the
-        <code>org.apache.catalina.realm.X509UsernameRetriever</code>
-        interface. The default is to use the certificate's SubjectDN
-        as the username.</p>
-      </attribute>
-    </attributes>
-
-    <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
-    information on setting up container managed security using the
-    JDBC Database Realm component.</p>
-
-  </subsection>
-
-
   <subsection name="DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm">
 
     <p>The <strong>DataSource Database Realm</strong> connects Tomcat to
@@ -357,7 +226,6 @@
     roles. Changes to the directory are immediately reflected in the
     information used to authenticate new logins.</p>
 
-
     <p>The directory realm supports a variety of approaches to using
     LDAP for authentication:</p>
 
@@ -1176,6 +1044,136 @@
 
   </subsection>
 
+  <subsection name="JDBC Database Realm - org.apache.catalina.realm.JDBCRealm">
+
+    <p>The <strong>JDBC Database Realm</strong> connects Tomcat to
+    a relational database, accessed through an appropriate JDBC driver,
+    to perform lookups of usernames, passwords, and their associated
+    roles.  Because the lookup is done each time that it is required,
+    changes to the database will be immediately reflected in the
+    information used to authenticate new logins.</p>
+
+    <p>A rich set of additional attributes lets you configure the required
+    connection to the underlying database, as well as the table and
+    column names used to retrieve the required information:</p>
+
+    <attributes>
+
+      <attribute name="allRolesMode" required="false">
+        <p>This attribute controls how the special role name <code>*</code> is
+        handled when processing authorization constraints in web.xml. By
+        default, the specification compliant value of <code>strict</code> is
+        used which means that the user must be assigned one of the roles defined
+        in web.xml. The alternative values are <code>authOnly</code> which means
+        that the user must be authenticated but no check is made for assigned
+        roles and <code>strictAuthOnly</code> which means that the user must be
+        authenticated and no check will be made for assigned roles unless roles
+        are defined in web.xml in which case the user must be assigned at least
+        one of those roles.</p>
+        <p>When this attribute has the value of <code>authOnly</code> or
+        <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and
+        <strong>userRoleTable</strong> attributes become optional. If those two
+        attributes are omitted, the user's roles will not be loaded by this
+        Realm.</p>
+      </attribute>
+
+      <attribute name="connectionName" required="true">
+        <p>The database username to use when establishing the JDBC
+        connection.</p>
+      </attribute>
+
+      <attribute name="connectionPassword" required="true">
+        <p>The database password to use when establishing the JDBC
+        connection.</p>
+      </attribute>
+
+      <attribute name="connectionURL" required="true">
+        <p>The connection URL to be passed to the JDBC driver when
+        establishing a database connection.</p>
+      </attribute>
+
+      <attribute name="digest" required="false">
+        <p>The name of the <code>MessageDigest</code> algorithm used
+        to encode user passwords stored in the database.  If not specified,
+        user passwords are assumed to be stored in clear-text.</p>
+      </attribute>
+
+      <attribute name="digestEncoding" required="false">
+        <p>The charset for encoding digests.  If not specified, the platform
+        default will be used.</p>
+      </attribute>
+
+      <attribute name="driverName" required="true">
+        <p>Fully qualified Java class name of the JDBC driver to be
+        used to connect to the authentication database.</p>
+      </attribute>
+
+      <attribute name="roleNameCol" required="false">
+        <p>Name of the column, in the "user roles" table, which contains
+        a role name assigned to the corresponding user.</p>
+        <p>This attribute is <strong>required</strong> in majority of
+        configurations. See <strong>allRolesMode</strong> attribute for
+        a rare case when it can be omitted.</p>
+      </attribute>
+
+      <attribute name="stripRealmForGss" required="false">
+        <p>When processing users authenticated via the GSS-API, this attribute
+        controls if any &quot;@...&quot; is removed from the end of the user
+        name. If not specified, the default is <code>true</code>.</p>
+      </attribute>
+
+      <attribute name="transportGuaranteeRedirectStatus" required="false">
+        <p>The HTTP status code to use when the container needs to issue an HTTP
+           redirect to meet the requirements of a configured transport
+           guarantee. The provided status code is not validated. If not
+           specified, the default value of <code>302</code> is used.</p>
+      </attribute>
+
+      <attribute name="userCredCol" required="true">
+        <p>Name of the column, in the "users" table, which contains
+        the user's credentials (i.e. password).  If a value for the
+        <code>digest</code> attribute is specified, this component
+        will assume that the passwords have been encoded with the
+        specified algorithm.  Otherwise, they will be assumed to be
+        in clear text.</p>
+      </attribute>
+
+      <attribute name="userNameCol" required="true">
+        <p>Name of the column, in the "users" and "user roles" table,
+        that contains the user's username.</p>
+      </attribute>
+
+      <attribute name="userRoleTable" required="false">
+        <p>Name of the "user roles" table, which must contain columns
+        named by the <code>userNameCol</code> and <code>roleNameCol</code>
+        attributes.</p>
+        <p>This attribute is <strong>required</strong> in majority of
+        configurations. See <strong>allRolesMode</strong> attribute for
+        a rare case when it can be omitted.</p>
+      </attribute>
+
+      <attribute name="userTable" required="true">
+        <p>Name of the "users" table, which must contain columns named
+        by the <code>userNameCol</code> and <code>userCredCol</code>
+        attributes.</p>
+      </attribute>
+
+      <attribute name="X509UsernameRetrieverClassName" required="false">
+        <p>When using X509 client certificates, this specifies the class name
+        that will be used to retrieve the user name from the certificate.
+        The class must implement the
+        <code>org.apache.catalina.realm.X509UsernameRetriever</code>
+        interface. The default is to use the certificate's SubjectDN
+        as the username.</p>
+      </attribute>
+    </attributes>
+
+    <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
+    information on setting up container managed security using the
+    JDBC Database Realm component.</p>
+
+  </subsection>
+
 </section>
 
 
diff --git a/webapps/docs/host-manager-howto.xml b/webapps/docs/host-manager-howto.xml
index bd96a2d..09c27da 100644
--- a/webapps/docs/host-manager-howto.xml
+++ b/webapps/docs/host-manager-howto.xml
@@ -114,10 +114,9 @@ OK - Listed hosts
 localhost:</source>
   </p>
   <p>
-    Note that in case you retrieve your users using the
-    <code>DataSourceRealm</code>, <code>JDBCRealm</code>, or
-    <code>JNDIRealm</code> mechanism, add the appropriate role in the database
-    or the directory server respectively.
+    If you are using a different realm you will need to add the necessary role
+    to the appropriate user(s) using the standard user management tools for that
+    realm.
   </p>
 </section>
 <section name="List of Commands">
diff --git a/webapps/docs/html-host-manager-howto.xml b/webapps/docs/html-host-manager-howto.xml
index f59072a..967430a 100644
--- a/webapps/docs/html-host-manager-howto.xml
+++ b/webapps/docs/html-host-manager-howto.xml
@@ -114,10 +114,9 @@
       log in with the created credentials.
     </p>
     <p>
-      Note that in case you retrieve your users using the
-      <code>DataSourceRealm</code>, <code>JDBCRealm</code>, or
-      <code>JNDIRealm</code> mechanism, add the appropriate role in the database
-      or the directory server respectively.
+      If you are using a different realm you will need to add the necessary role
+      to the appropriate user(s) using the standard user management tools for
+      that realm.
     </p>
   </section>
 
diff --git a/webapps/docs/realm-howto.xml b/webapps/docs/realm-howto.xml
index 854aee3..d52a003 100644
--- a/webapps/docs/realm-howto.xml
+++ b/webapps/docs/realm-howto.xml
@@ -269,119 +269,6 @@ users.</p>
 
 <section name="Standard Realm Implementations">
 
-<subsection name="JDBCRealm">
-
-<h3>Introduction</h3>
-
-<p><strong>JDBCRealm</strong> is an implementation of the Tomcat
-<code>Realm</code> interface that looks up users in a relational database
-accessed via a JDBC driver.  There is substantial configuration flexibility
-that lets you adapt to existing table and column names, as long as your
-database structure conforms to the following requirements:</p>
-<ul>
-<li>There must be a table, referenced below as the <em>users</em> table,
-    that contains one row for every valid user that this <code>Realm</code>
-    should recognize.</li>
-<li>The <em>users</em> table must contain at least two columns (it may
-    contain more if your existing applications required it):
-    <ul>
-    <li>Username to be recognized by Tomcat when the user logs in.</li>
-    <li>Password to be recognized by Tomcat when the user logs in.
-        This value may in cleartext or digested - see below for more
-        information.</li>
-    </ul></li>
-<li>There must be a table, referenced below as the <em>user roles</em> table,
-    that contains one row for every valid role that is assigned to a
-    particular user.  It is legal for a user to have zero, one, or more than
-    one valid role.</li>
-<li>The <em>user roles</em> table must contain at least two columns (it may
-    contain more if your existing applications required it):
-    <ul>
-    <li>Username to be recognized by Tomcat (same value as is specified
-        in the <em>users</em> table).</li>
-    <li>Role name of a valid role associated with this user.</li>
-    </ul></li>
-</ul>
-
-<h3>Quick Start</h3>
-
-<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
-<ol>
-<li>If you have not yet done so, create tables and columns in your database
-    that conform to the requirements described above.</li>
-<li>Configure a database username and password for use by Tomcat, that has
-    at least read only access to the tables described above.  (Tomcat will
-    never attempt to write to these tables.)</li>
-<li>Place a copy of the JDBC driver you will be using inside the
-    <code>$CATALINA_HOME/lib</code> directory.
-    Note that <strong>only</strong> JAR files are recognized!</li>
-<li>Set up a <code>&lt;Realm&gt;</code> element, as described below, in your
-    <code>$CATALINA_BASE/conf/server.xml</code> file.</li>
-<li>Restart Tomcat if it is already running.</li>
-</ol>
-
-<h3>Realm Element Attributes</h3>
-
-<p>To configure JDBCRealm, you will create a <code>&lt;Realm&gt;</code>
-element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
-as described <a href="#Configuring a Realm">above</a>. The attributes for the
-JDBCRealm are defined in the <a href="config/realm.html">Realm</a> configuration
-documentation.</p>
-
-<h3>Example</h3>
-
-<p>An example SQL script to create the needed tables might look something
-like this (adapt the syntax as required for your particular database):</p>
-<source>
-create table users (
-  user_name         varchar(15) not null primary key,
-  user_pass         varchar(15) not null
-);
-
-create table user_roles (
-  user_name         varchar(15) not null,
-  role_name         varchar(15) not null,
-  primary key (user_name, role_name)
-);
-</source>
-
-<p>Example <code>Realm</code> elements are included (commented out) in the
-default <code>$CATALINA_BASE/conf/server.xml</code> file.  Here's an example
-for using a MySQL database called "authority", configured with the tables
-described above, and accessed with username "dbuser" and password "dbpass":</p>
-<source>
-&lt;Realm className="org.apache.catalina.realm.JDBCRealm"
-      driverName="org.gjt.mm.mysql.Driver"
-   connectionURL="jdbc:mysql://localhost/authority?user=dbuser&amp;amp;password=dbpass"
-       userTable="users" userNameCol="user_name" userCredCol="user_pass"
-   userRoleTable="user_roles" roleNameCol="role_name"/&gt;
-</source>
-
-<h3>Additional Notes</h3>
-
-<p>JDBCRealm operates according to the following rules:</p>
-<ul>
-<li>When a user attempts to access a protected resource for the first time,
-    Tomcat will call the <code>authenticate()</code> method of this
-    <code>Realm</code>.  Thus, any changes you have made to the database
-    directly (new users, changed passwords or roles, etc.) will be immediately
-    reflected.</li>
-<li>Once a user has been authenticated, the user (and his or her associated
-    roles) are cached within Tomcat for the duration of the user's login.
-    (For FORM-based authentication, that means until the session times out or
-    is invalidated; for BASIC authentication, that means until the user
-    closes their browser).  The cached user is <strong>not</strong> saved and
-    restored across sessions serialisations. Any changes to the database
-    information for an already authenticated user will <strong>not</strong> be
-    reflected until the next time that user logs on again.</li>
-<li>Administering the information in the <em>users</em> and <em>user roles</em>
-    table is the responsibility of your own applications.  Tomcat does not
-    provide any built-in capabilities to maintain users and roles.</li>
-</ul>
-
-</subsection>
-
-
 <subsection name="DataSourceRealm">
 
 <h3>Introduction</h3>
@@ -1219,6 +1106,118 @@ functionality to a UserDatabase Realm.</p>
 
 </subsection>
 
+<subsection name="JDBCRealm">
+
+<h3>Introduction</h3>
+
+<p><strong>JDBCRealm</strong> is an implementation of the Tomcat
+<code>Realm</code> interface that looks up users in a relational database
+accessed via a JDBC driver.  There is substantial configuration flexibility
+that lets you adapt to existing table and column names, as long as your
+database structure conforms to the following requirements:</p>
+<ul>
+<li>There must be a table, referenced below as the <em>users</em> table,
+    that contains one row for every valid user that this <code>Realm</code>
+    should recognize.</li>
+<li>The <em>users</em> table must contain at least two columns (it may
+    contain more if your existing applications required it):
+    <ul>
+    <li>Username to be recognized by Tomcat when the user logs in.</li>
+    <li>Password to be recognized by Tomcat when the user logs in.
+        This value may in cleartext or digested - see below for more
+        information.</li>
+    </ul></li>
+<li>There must be a table, referenced below as the <em>user roles</em> table,
+    that contains one row for every valid role that is assigned to a
+    particular user.  It is legal for a user to have zero, one, or more than
+    one valid role.</li>
+<li>The <em>user roles</em> table must contain at least two columns (it may
+    contain more if your existing applications required it):
+    <ul>
+    <li>Username to be recognized by Tomcat (same value as is specified
+        in the <em>users</em> table).</li>
+    <li>Role name of a valid role associated with this user.</li>
+    </ul></li>
+</ul>
+
+<h3>Quick Start</h3>
+
+<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
+<ol>
+<li>If you have not yet done so, create tables and columns in your database
+    that conform to the requirements described above.</li>
+<li>Configure a database username and password for use by Tomcat, that has
+    at least read only access to the tables described above.  (Tomcat will
+    never attempt to write to these tables.)</li>
+<li>Place a copy of the JDBC driver you will be using inside the
+    <code>$CATALINA_HOME/lib</code> directory.
+    Note that <strong>only</strong> JAR files are recognized!</li>
+<li>Set up a <code>&lt;Realm&gt;</code> element, as described below, in your
+    <code>$CATALINA_BASE/conf/server.xml</code> file.</li>
+<li>Restart Tomcat if it is already running.</li>
+</ol>
+
+<h3>Realm Element Attributes</h3>
+
+<p>To configure JDBCRealm, you will create a <code>&lt;Realm&gt;</code>
+element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
+as described <a href="#Configuring a Realm">above</a>. The attributes for the
+JDBCRealm are defined in the <a href="config/realm.html">Realm</a> configuration
+documentation.</p>
+
+<h3>Example</h3>
+
+<p>An example SQL script to create the needed tables might look something
+like this (adapt the syntax as required for your particular database):</p>
+<source>
+create table users (
+  user_name         varchar(15) not null primary key,
+  user_pass         varchar(15) not null
+);
+
+create table user_roles (
+  user_name         varchar(15) not null,
+  role_name         varchar(15) not null,
+  primary key (user_name, role_name)
+);
+</source>
+
+<p>Example <code>Realm</code> elements are included (commented out) in the
+default <code>$CATALINA_BASE/conf/server.xml</code> file.  Here's an example
+for using a MySQL database called "authority", configured with the tables
+described above, and accessed with username "dbuser" and password "dbpass":</p>
+<source>
+&lt;Realm className="org.apache.catalina.realm.JDBCRealm"
+      driverName="org.gjt.mm.mysql.Driver"
+   connectionURL="jdbc:mysql://localhost/authority?user=dbuser&amp;amp;password=dbpass"
+       userTable="users" userNameCol="user_name" userCredCol="user_pass"
+   userRoleTable="user_roles" roleNameCol="role_name"/&gt;
+</source>
+
+<h3>Additional Notes</h3>
+
+<p>JDBCRealm operates according to the following rules:</p>
+<ul>
+<li>When a user attempts to access a protected resource for the first time,
+    Tomcat will call the <code>authenticate()</code> method of this
+    <code>Realm</code>.  Thus, any changes you have made to the database
+    directly (new users, changed passwords or roles, etc.) will be immediately
+    reflected.</li>
+<li>Once a user has been authenticated, the user (and his or her associated
+    roles) are cached within Tomcat for the duration of the user's login.
+    (For FORM-based authentication, that means until the session times out or
+    is invalidated; for BASIC authentication, that means until the user
+    closes their browser).  The cached user is <strong>not</strong> saved and
+    restored across sessions serialisations. Any changes to the database
+    information for an already authenticated user will <strong>not</strong> be
+    reflected until the next time that user logs on again.</li>
+<li>Administering the information in the <em>users</em> and <em>user roles</em>
+    table is the responsibility of your own applications.  Tomcat does not
+    provide any built-in capabilities to maintain users and roles.</li>
+</ul>
+
+</subsection>
+
 </section>
 
 </body>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[tomcat] 02/02: Deprecate JDBCRealm

markt
In reply to this post by markt
This is an automated email from the ASF dual-hosted git repository.

markt pushed a commit to branch 7.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git

commit 15bbc3d545f4052b082ea726ec66bc7a20dd0460
Author: Mark Thomas <[hidden email]>
AuthorDate: Tue Sep 15 14:44:40 2020 +0100

    Deprecate JDBCRealm
---
 java/org/apache/catalina/mbeans/MBeanFactory.java      | 7 +++++--
 java/org/apache/catalina/mbeans/mbeans-descriptors.xml | 2 +-
 java/org/apache/catalina/realm/DataSourceRealm.java    | 2 +-
 java/org/apache/catalina/realm/JDBCRealm.java          | 4 ++++
 webapps/docs/changelog.xml                             | 3 +++
 webapps/docs/config/realm.xml                          | 3 +++
 webapps/docs/realm-howto.xml                           | 3 +++
 7 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/java/org/apache/catalina/mbeans/MBeanFactory.java b/java/org/apache/catalina/mbeans/MBeanFactory.java
index c1580a5..1dce4b0 100644
--- a/java/org/apache/catalina/mbeans/MBeanFactory.java
+++ b/java/org/apache/catalina/mbeans/MBeanFactory.java
@@ -39,7 +39,6 @@ import org.apache.catalina.core.StandardHost;
 import org.apache.catalina.core.StandardService;
 import org.apache.catalina.loader.WebappLoader;
 import org.apache.catalina.realm.DataSourceRealm;
-import org.apache.catalina.realm.JDBCRealm;
 import org.apache.catalina.realm.JNDIRealm;
 import org.apache.catalina.realm.MemoryRealm;
 import org.apache.catalina.realm.UserDatabaseRealm;
@@ -392,13 +391,17 @@ public class MBeanFactory {
      * @return the object name of the created realm
      *
      * @exception Exception if an MBean cannot be created or registered
+     *
+     * @deprecated This method will be removed in Tomcat 10. Use a
+     *             DataSourceRealm instead.
      */
+    @Deprecated
     public String createJDBCRealm(String parent, String driverName,
         String connectionName, String connectionPassword, String connectionURL)
         throws Exception {
 
         // Create a new JDBCRealm instance
-        JDBCRealm realm = new JDBCRealm();
+        org.apache.catalina.realm.JDBCRealm realm = new org.apache.catalina.realm.JDBCRealm();
         realm.setDriverName(driverName);
         realm.setConnectionName(connectionName);
         realm.setConnectionPassword(connectionPassword);
diff --git a/java/org/apache/catalina/mbeans/mbeans-descriptors.xml b/java/org/apache/catalina/mbeans/mbeans-descriptors.xml
index 6c59c00..168d45e 100644
--- a/java/org/apache/catalina/mbeans/mbeans-descriptors.xml
+++ b/java/org/apache/catalina/mbeans/mbeans-descriptors.xml
@@ -115,7 +115,7 @@
     </operation>
 
     <operation   name="createJDBCRealm"
-          description="Create a new JDBC Realm"
+          description="Create a new JDBC Realm (deprecated - will be removed in Tomcat 10)"
                impact="ACTION"
            returnType="java.lang.String">
       <parameter name="parent"
diff --git a/java/org/apache/catalina/realm/DataSourceRealm.java b/java/org/apache/catalina/realm/DataSourceRealm.java
index 97ddf07..9020597 100644
--- a/java/org/apache/catalina/realm/DataSourceRealm.java
+++ b/java/org/apache/catalina/realm/DataSourceRealm.java
@@ -35,7 +35,7 @@ import org.apache.naming.ContextBindings;
 /**
 *
 * Implementation of <b>Realm</b> that works with any JDBC JNDI DataSource.
-* See the JDBCRealm.howto for more details on how to set up the database and
+* See the Realm How-To for more details on how to set up the database and
 * for configuration options.
 *
 * @author Glenn L. Nielsen
diff --git a/java/org/apache/catalina/realm/JDBCRealm.java b/java/org/apache/catalina/realm/JDBCRealm.java
index 9679de2..76d0751 100644
--- a/java/org/apache/catalina/realm/JDBCRealm.java
+++ b/java/org/apache/catalina/realm/JDBCRealm.java
@@ -47,7 +47,11 @@ import org.apache.tomcat.util.ExceptionUtils;
 * @author Craig R. McClanahan
 * @author Carson McDonald
 * @author Ignacio Ortega
+*
+* @deprecated Will be removed in Tomcat 10 onwards. Use the DataSourceRealm
+*             instead.
 */
+@Deprecated
 public class JDBCRealm
     extends RealmBase {
 
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index eb0ee90..b675d3b 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -80,6 +80,9 @@
         the requested resource. Based on a pull request by Sergey Ponomarev.
         (markt)
       </fix>
+      <update>
+        Deprecate the JDBCRealm. (markt)
+      </update>
     </changelog>
   </subsection>
   <subsection name="Coyote">
diff --git a/webapps/docs/config/realm.xml b/webapps/docs/config/realm.xml
index b536e13..66a3b6e 100644
--- a/webapps/docs/config/realm.xml
+++ b/webapps/docs/config/realm.xml
@@ -1046,6 +1046,9 @@
 
   <subsection name="JDBC Database Realm - org.apache.catalina.realm.JDBCRealm">
 
+    <p><strong>The JDBC Database Realm has been deprecated and will be removed
+    in Tomcat 10 onwards. Use the DataSourceRealm instead.</strong></p>
+
     <p>The <strong>JDBC Database Realm</strong> connects Tomcat to
     a relational database, accessed through an appropriate JDBC driver,
     to perform lookups of usernames, passwords, and their associated
diff --git a/webapps/docs/realm-howto.xml b/webapps/docs/realm-howto.xml
index d52a003..29e637d 100644
--- a/webapps/docs/realm-howto.xml
+++ b/webapps/docs/realm-howto.xml
@@ -1110,6 +1110,9 @@ functionality to a UserDatabase Realm.</p>
 
 <h3>Introduction</h3>
 
+<p><strong>The JDBC Database Realm has been deprecated and will be removed
+in Tomcat 10 onwards. Use the DataSourceRealm instead.</strong></p>
+
 <p><strong>JDBCRealm</strong> is an implementation of the Tomcat
 <code>Realm</code> interface that looks up users in a relational database
 accessed via a JDBC driver.  There is substantial configuration flexibility


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]