This is an automated email from the ASF dual-hosted git repository.
remm pushed a commit to branch 10.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/10.0.x by this push:
new 312b8b7 Fix docs inconsistencies
312b8b7 is described below
commit 312b8b7c648ceb9851c1afe0e2a2cd93c99dc391
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 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-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
