[tomcat] branch main updated: Fix docs inconsistencies

[re...@apache.org]

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

remm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git


The following commit(s) were added to refs/heads/main by this push:
     new 92ccdb3  Fix docs inconsistencies
92ccdb3 is described below

commit 92ccdb339fff3e3e06d57fd28389ceb9ad9cecf1
Author: remm <re...@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 32c28b0..76e00ef 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 9f19c6d..d03291c 100644
--- a/webapps/docs/realm-howto.xml
+++ b/webapps/docs/realm-howto.xml
@@ -809,8 +809,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>
 
@@ -836,12 +836,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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org