This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit 3b15ba95dc681a39ea6115cfc351c0270f2dbfea
Author: Mark Thomas <ma...@apache.org>
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 | 244 ++++++++++++++++---------------
webapps/docs/host-manager-howto.xml | 7 +-
webapps/docs/html-host-manager-howto.xml | 7 +-
webapps/docs/realm-howto.xml | 217 ++++++++++++++-------------
5 files changed, 238 insertions(+), 239 deletions(-)
diff --git a/webapps/docs/appdev/deployment.xml
b/webapps/docs/appdev/deployment.xml
index f479f97..77395a4 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 aa5e5b9..f18eacc 100644
--- a/webapps/docs/config/realm.xml
+++ b/webapps/docs/config/realm.xml
@@ -92,126 +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="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 "@..." 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
- <code>CredentialHandler</code> 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
@@ -340,7 +220,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 +1055,129 @@
</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>Note: The <strong>JDBC Database Realm</strong> uses a single connection
+ to the database with synchronisation to prevenbt concurrent usage. It is
not
+ recommended for production usage. Use the DataSource Realm instaead.</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="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 "@..." 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
+ <code>CredentialHandler</code> 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 fb1ccfd..1530bc1 100644
--- a/webapps/docs/host-manager-howto.xml
+++ b/webapps/docs/host-manager-howto.xml
@@ -111,10 +111,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 59ea49c..6a9d464 100644
--- a/webapps/docs/html-host-manager-howto.xml
+++ b/webapps/docs/html-host-manager-howto.xml
@@ -111,10 +111,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 aa6fe88..c70fc92 100644
--- a/webapps/docs/realm-howto.xml
+++ b/webapps/docs/realm-howto.xml
@@ -300,115 +300,6 @@ users.</p>
<section name="Standard Realm Implementations">
-<subsection name="JDBCRealm">
-
-<h5>Introduction</h5>
-
-<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>
-
-<h5>Quick Start</h5>
-
-<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><Realm></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>
-
-<h5>Realm Element Attributes</h5>
-
-<p>To configure JDBCRealm, you will create a <code><Realm></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>
-
-<h5>Example</h5>
-
-<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><![CDATA[<Realm className="org.apache.catalina.realm.JDBCRealm"
- driverName="org.gjt.mm.mysql.Driver"
-
connectionURL="jdbc:mysql://localhost/authority?user=dbuser&password=dbpass"
- userTable="users" userNameCol="user_name" userCredCol="user_pass"
- userRoleTable="user_roles" roleNameCol="role_name"/>]]></source>
-
-<h5>Additional Notes</h5>
-
-<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">
<h5>Introduction</h5>
@@ -1220,6 +1111,114 @@ functionality to a UserDatabase Realm.</p>
</subsection>
+<subsection name="JDBCRealm">
+
+<h5>Introduction</h5>
+
+<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>
+
+<h5>Quick Start</h5>
+
+<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><Realm></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>
+
+<h5>Realm Element Attributes</h5>
+
+<p>To configure JDBCRealm, you will create a <code><Realm></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>
+
+<h5>Example</h5>
+
+<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><![CDATA[<Realm className="org.apache.catalina.realm.JDBCRealm"
+ driverName="org.gjt.mm.mysql.Driver"
+
connectionURL="jdbc:mysql://localhost/authority?user=dbuser&password=dbpass"
+ userTable="users" userNameCol="user_name" userCredCol="user_pass"
+ userRoleTable="user_roles" roleNameCol="role_name"/>]]></source>
+
+<h5>Additional Notes</h5>
+
+<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: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
