This is an automated email from the ASF dual-hosted git repository.
markt 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 48120b6bf7 Additional documentation, Javadoc and comments for SSO.
48120b6bf7 is described below
commit 48120b6bf7c7a1fd32a6aafe27b2edc6a11f3bdb
Author: Mark Thomas <[email protected]>
AuthorDate: Fri Nov 28 13:15:58 2025 +0000
Additional documentation, Javadoc and comments for SSO.
---
.../authenticator/DigestAuthenticator.java | 20 ++++++++------
.../catalina/authenticator/SSLAuthenticator.java | 21 +++++++++------
.../catalina/authenticator/SingleSignOn.java | 31 ++++++++++++++++++++--
.../authenticator/SpnegoAuthenticator.java | 9 +++++++
webapps/docs/config/valve.xml | 25 ++++++++++++-----
5 files changed, 81 insertions(+), 25 deletions(-)
diff --git a/java/org/apache/catalina/authenticator/DigestAuthenticator.java
b/java/org/apache/catalina/authenticator/DigestAuthenticator.java
index d62c45cf5d..2a8c8637ef 100644
--- a/java/org/apache/catalina/authenticator/DigestAuthenticator.java
+++ b/java/org/apache/catalina/authenticator/DigestAuthenticator.java
@@ -263,14 +263,18 @@ public class DigestAuthenticator extends
AuthenticatorBase {
@Override
protected boolean doAuthenticate(Request request, HttpServletResponse
response) throws IOException {
- // NOTE: We don't try to reauthenticate using any existing SSO session,
- // because that will only work if the original authentication was
- // BASIC or FORM, which are less secure than the DIGEST auth-type
- // specified for this webapp
- //
- // Change to true below to allow previous FORM or BASIC authentications
- // to authenticate users for this webapp
- // TODO make this a configurable attribute (in SingleSignOn??)
+ /*
+ * Reauthentication using the cached user name and password (if any)
is not enabled for DIGEST authentication.
+ * This was an historical design decision made because DIGEST
authentication is viewed as more secure than
+ * BASIC/FORM.
+ *
+ * However, reauthentication was introduced to handle the case where
the Realm took additional actions on
+ * authentication. Reauthenticating with the cached user name and
password should be sufficient for DIGEST in
+ * that scenario. However, the original behaviour to reauthenticate
has been retained in case of any (very
+ * unlikely) backwards compatibility issues.
+ *
+ * TODO: Make the reauthentication behaviour configurable per
authenticator.
+ */
if (checkForCachedAuthentication(request, response, false)) {
return true;
}
diff --git a/java/org/apache/catalina/authenticator/SSLAuthenticator.java
b/java/org/apache/catalina/authenticator/SSLAuthenticator.java
index 37181c2c96..334892c78b 100644
--- a/java/org/apache/catalina/authenticator/SSLAuthenticator.java
+++ b/java/org/apache/catalina/authenticator/SSLAuthenticator.java
@@ -59,14 +59,19 @@ public class SSLAuthenticator extends AuthenticatorBase {
@Override
protected boolean doAuthenticate(Request request, HttpServletResponse
response) throws IOException {
- // NOTE: We don't try to reauthenticate using any existing SSO session,
- // because that will only work if the original authentication was
- // BASIC or FORM, which are less secure than the CLIENT-CERT auth-type
- // specified for this webapp
- //
- // Change to true below to allow previous FORM or BASIC authentications
- // to authenticate users for this webapp
- // TODO make this a configurable attribute (in SingleSignOn??)
+ /*
+ * Reauthentication using the cached user name and password (if any)
is not enabled for CLIENT-CERT
+ * authentication. This was an historical design decision made because
CLIENT-CERT authentication is viewed as
+ * more secure than BASIC/FORM.
+ *
+ * However, reauthentication was introduced to handle the case where
the Realm took additional actions on
+ * authentication. Reauthenticating with the cached user name and
password may not be sufficient for CLIENT-CERT
+ * since it will not make any TLS information (client certificate etc)
available that a web application may
+ * depend on. Therefore, the reauthentication behaviour for
CLIENT-CERT is to perform a normal CLIENT-CERT
+ * authentication.
+ *
+ * TODO: Make the reauthentication behaviour configurable per
authenticator.
+ */
if (checkForCachedAuthentication(request, response, false)) {
return true;
}
diff --git a/java/org/apache/catalina/authenticator/SingleSignOn.java
b/java/org/apache/catalina/authenticator/SingleSignOn.java
index 5f277c4a9d..e28313f014 100644
--- a/java/org/apache/catalina/authenticator/SingleSignOn.java
+++ b/java/org/apache/catalina/authenticator/SingleSignOn.java
@@ -51,6 +51,33 @@ import org.apache.tomcat.util.res.StringManager;
* <li>The web applications themselves must use one of the standard
Authenticators found in the
* <code>org.apache.catalina.authenticator</code> package.</li>
* </ul>
+ * <p>
+ * On first authentication to any web application, an SSO session is created
and the authenticated Principal, the
+ * authentication type and the plain text user name and password used to
authenticate (if available) are cached using a
+ * key based on the SSO session. On subsequent requests to a web application
on the Host where this Valve is configured,
+ * the cached authenticated Principal and the authentication type are added to
the request by the SSO Valve and no
+ * further authentication takes place.
+ * <p>
+ * In some scenarios, adding the authenticated Principal and the
authentication type is insufficient. This usually
+ * occurs when the web application depends on additional actions the Realm
takes on authentication which are bypassed by
+ * the SSO Valve. Examples of this include the Realm setting security
credentials on the request thread to support EJB
+ * access or the CLIENT-CERT authenticator providing the client certificate
and other TLS attributes. To address this,
+ * the {@code requireReauthentication} flag can be set to {@code true} which
will cause the SSO Valve not to set the
+ * cached Principal and authentication type on the request and the web
application authenticator will authenticate the
+ * request. By default this reauthentication will occur in the following ways:
+ * <ul>
+ * <li>BASIC - call the realm using the plain text user name and password
cached by the SSO Valve if available. If not
+ * cached, obtain those values from the request. If not present in the
request, request them from the user agent.</li>
+ * <li>FORM - call the realm using the plain text user name and password
cached by the SSO Valve if available. If not
+ * cached, request them from the user agent.</li>
+ * <li>DIGEST - call the realm using the credentials present in the request.
If not present in the request, request them
+ * from the user agent.</li>
+ * <li>CLIENT-CERT - call the realm using the credentials present in the TLS
connection. If not present in the TLS
+ * connection, request them from the user agent.</li>
+ * <li>SPNEGO - call the realm using the plain text user name and password
cached by the SSO Valve if available. If not
+ * cached, request authentication credentials from the user agent.</li>
+ * Note that this means that enabling reauthentication only makes sense if
there are two or more web applications in the
+ * Host that use BASIC, FORM or SPNEGO. If that is not the case, the SSO Valve
will just add processing overhead.
*/
public class SingleSignOn extends ValveBase {
@@ -435,8 +462,8 @@ public class SingleSignOn extends ValveBase {
/**
- * Attempts reauthentication to the given <code>Realm</code> using the
credentials associated with the single
- * sign-on session identified by argument <code>ssoId</code>.
+ * Attempts reauthentication to the given <code>Realm</code> using the
cached plain text credentials associated with
+ * the single sign-on session identified by argument <code>ssoId</code>.
* <p>
* If reauthentication is successful, the <code>Principal</code> and
authorization type associated with the SSO
* session will be bound to the given <code>Request</code> object via
calls to {@link Request#setAuthType
diff --git a/java/org/apache/catalina/authenticator/SpnegoAuthenticator.java
b/java/org/apache/catalina/authenticator/SpnegoAuthenticator.java
index ea35a44373..2ed169bae5 100644
--- a/java/org/apache/catalina/authenticator/SpnegoAuthenticator.java
+++ b/java/org/apache/catalina/authenticator/SpnegoAuthenticator.java
@@ -134,6 +134,15 @@ public class SpnegoAuthenticator extends AuthenticatorBase
{
@Override
protected boolean doAuthenticate(Request request, HttpServletResponse
response) throws IOException {
+ /*
+ * Reauthentication using the cached user name and password (if any)
is enabled for SPNEGO authentication.
+ *
+ * Reauthentication was introduced to handle the case where the Realm
took additional actions on authentication.
+ * Reauthenticating with the cached user name and password may not be
sufficient for SPNEGO in that scenario
+ * since the delegated credentials will not be available.
+ *
+ * TODO: Make the reauthentication behaviour configurable per
authenticator.
+ */
if (checkForCachedAuthentication(request, response, true)) {
return true;
}
diff --git a/webapps/docs/config/valve.xml b/webapps/docs/config/valve.xml
index f20de0d87c..e68ce80529 100644
--- a/webapps/docs/config/valve.xml
+++ b/webapps/docs/config/valve.xml
@@ -1367,7 +1367,9 @@
<p>The <em>Single Sign On Valve</em> is utilized when you wish to give
users
the ability to sign on to any one of the web applications associated with
your virtual host, and then have their identity recognized by all other
- web applications on the same virtual host.</p>
+ web applications on the same virtual host. The SSO Valve caches the
+ authenticated Principal and authentication type and provides them to all
web
+ applications.</p>
<p>See the <a href="host.html#Single_Sign_On">Single Sign On</a> special
feature on the <strong>Host</strong> element for more information.</p>
@@ -1389,12 +1391,21 @@
<attribute name="requireReauthentication" required="false">
<p>Default false. Flag to determine whether each request needs to be
- reauthenticated to the security <strong>Realm</strong>. If "true", this
- Valve uses cached security credentials (username and password) to
- reauthenticate to the <strong>Realm</strong> each request associated
- with an SSO session. If "false", the Valve can itself authenticate
- requests based on the presence of a valid SSO cookie, without
- rechecking with the <strong>Realm</strong>.</p>
+ reauthenticated to the security <strong>Realm</strong>. This is
required
+ if the Realm or the authentication process provides additional
+ information (beyond added an authenticated Principal) to the request
+ that is required by a web application.</p>
+ <p>If "true", this Valve uses cached security credentials (username and
+ password) to reauthenticate to the <strong>Realm</strong> each request
+ associated with an SSO session where the web application is configured
+ with BASIC, FORM or SPNEGO authentication. Web applications using
DIGEST
+ or CLIENT-CERT authentication will reauthenticate using the standard
+ authentication process for the authenticator. Therefore, it only makes
+ sense to use the SSO Valve with this attribute set to "true" if there
+ are two or more web applications using BASIC, FORM or SPNEGO.</p>
+ <p>If "false", the Valve can itself authenticate requests based on the
+ presence of a valid SSO cookie, without rechecking with the
+ <strong>Realm</strong>.</p>
</attribute>
<attribute name="cookieDomain" required="false">
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
