This is an automated email from the ASF dual-hosted git repository.
remm pushed a commit to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/9.0.x by this push:
new cf29253 Fix docs inconsistencies
cf29253 is described below
commit cf29253074d82c954a96cf3d75df56f256f94e8e
Author: remm <r...@apache.org>
AuthorDate: Fri Sep 3 16:19:18 2021 +0200
Fix docs inconsistencies
---
webapps/docs/config/realm.xml | 3 +++
webapps/docs/realm-howto.xml | 20 ++++++++++++++------
2 files changed, 17 insertions(+), 6 deletions(-)
diff --git a/webapps/docs/config/realm.xml b/webapps/docs/config/realm.xml
index 4f6569e..51f586d 100644
--- a/webapps/docs/config/realm.xml
+++ b/webapps/docs/config/realm.xml
@@ -670,6 +670,9 @@
<p>This allows using a static <code>Principal</code> instance
disconnected from the database if needed. This makes the bahavior of
authenticated prinicipals equivalent to that of the other realms.
+ If there is a plan to use serialization, it is best to set this to
+ <code>true</code> as the principal will always be replaced by this
+ equivalent static principal when serializing.
If not specified, the default is <code>false</code>: use a
Principal connected to the UserDatabase.</p>
</attribute>
diff --git a/webapps/docs/realm-howto.xml b/webapps/docs/realm-howto.xml
index 2a358a8..5c68644 100644
--- a/webapps/docs/realm-howto.xml
+++ b/webapps/docs/realm-howto.xml
@@ -811,8 +811,8 @@ configuration documentation.</p>
<h5>User File Format</h5>
-<p>The users file uses the same format as the
-<a href="#MemoryRealm">MemoryRealm</a>.</p>
+<p>For the XML file based <code>UserDatabase</code>, the users file uses the
+same format as the <a href="#MemoryRealm">MemoryRealm</a>.</p>
<h5>Example</h5>
@@ -838,12 +838,20 @@ to all virtual hosts and web applications. The default
contents of the
<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>.</li>
-<li>Once a user has been authenticated, the user (and their associated
- roles) are cached within Tomcat for the duration of the user's login.
+<li>Once a user has been authenticated, the user becomes associated 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.</li>
+ closes their browser). However, the user roles will still reflect the
+ <code>UserDatabase</code> contents, unlike for the other realms. If a user
+ is removed from the database, it will be considered to have no roles.
+ The <code>useStaticPrincipal</code> attribute of the
+ <code>UserDatabaseRealm</code> can be used to instead cache the user along
+ with all its roles. The cached user is <strong>not</strong> saved and
+ restored across sessions serialisations. When the user's principal object
+ is serialized for any reason, it will also be replaced by a static
+ equivalent object with roles that will no longer reflect the databse
+ contents.</li>
</ul>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
