This is an automated email from the ASF dual-hosted git repository. quantranhong1999 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit a3d3d3e83c88ac9663cc4ced2db609886cbfd7b8 Author: Quan Tran <[email protected]> AuthorDate: Fri Jul 17 11:52:52 2026 +0700 JAMES-4210 Document POP3 authentication configuration --- docs/modules/servers/partials/configure/pop3.adoc | 30 ++++++++++++++++++++++ .../src/main/resources/pop3server.xml | 8 ++++++ src/site/xdoc/server/config-pop3.xml | 13 +++++++++- upgrade-instructions.md | 16 ++++++++++++ 4 files changed, 66 insertions(+), 1 deletion(-) diff --git a/docs/modules/servers/partials/configure/pop3.adoc b/docs/modules/servers/partials/configure/pop3.adoc index 9987551795..681d61d414 100644 --- a/docs/modules/servers/partials/configure/pop3.adoc +++ b/docs/modules/servers/partials/configure/pop3.adoc @@ -5,6 +5,36 @@ It contains one `pop3servers` element that can contain multiple `pop3server` ele The `pop3server` element can be configured using the common options described xref:{pages-path}/configure/server.adoc[here]. +== Authentication + +The optional `auth` element configures RFC 5034 AUTH. + +.`auth` element +|=== +| Property Name | Explanation + +| `auth.requireSSL` +| Configures whether plaintext password authentication requires a secure connection (TLS or STARTTLS). +It applies to both AUTH PLAIN and legacy USER/PASS, and defaults to `true` for these mechanisms. +OAuth mechanisms also honor this option when it is explicitly configured, but retain their historical default of `false` when it is absent. +Configure it to `true` when enabling OAuth bearer mechanisms, as bearer tokens must be protected by TLS. + +| `auth.plainAuthEnabled` +| Enables the PLAIN mechanism for AUTH. +It is an optional boolean that defaults to `true` and does not disable legacy USER/PASS authentication. + +| `auth.saslMechanisms` +| Configures an optional ordered, comma-separated list of SASL mechanism factory class names for Guice applications. +Built-in factories can use simple class names, while extensions use fully qualified class names. + +| `auth.oidc` +| Configures the OAUTHBEARER and XOAUTH2 mechanisms via OIDC. +The configuration is described in more detail xref:{pages-path}/configure/oidc.adoc[here]. + +|=== + +James advertises currently available SASL mechanisms through CAPA. + Additionally, it contains a mandatory `handlerchain` element that configures the behavior of the server using handlers. The `handlerchain` element has the following optional attributes: diff --git a/server/protocols/protocols-pop3/src/main/resources/pop3server.xml b/server/protocols/protocols-pop3/src/main/resources/pop3server.xml index aa973d9fb1..a5bcfc83a8 100644 --- a/server/protocols/protocols-pop3/src/main/resources/pop3server.xml +++ b/server/protocols/protocols-pop3/src/main/resources/pop3server.xml @@ -33,6 +33,14 @@ <connectiontimeout>1200</connectiontimeout> <connectionLimit> 0 </connectionLimit> <connectionLimitPerIP> 0 </connectionLimitPerIP> + <auth> + <!-- PLAIN through AUTH and legacy USER/PASS are available only after TLS by default. --> + <requireSSL>true</requireSSL> + <!-- Controls AUTH PLAIN only. Legacy USER/PASS remains enabled. --> + <plainAuthEnabled>true</plainAuthEnabled> + <!-- Guice applications can configure built-in simple names or extension factory FQCNs. --> + <!-- <saslMechanisms>PlainSaslMechanismFactory,OauthBearerSaslMechanismFactory,XOauth2SaslMechanismFactory</saslMechanisms> --> + </auth> <handlerchain enableJmx="true"> <handler class="org.apache.james.pop3server.core.CoreCmdHandlerLoader"/> </handlerchain> diff --git a/src/site/xdoc/server/config-pop3.xml b/src/site/xdoc/server/config-pop3.xml index 12eefe652a..706544a39d 100644 --- a/src/site/xdoc/server/config-pop3.xml +++ b/src/site/xdoc/server/config-pop3.xml @@ -66,6 +66,14 @@ <dd>Set the maximum simultaneous incoming connections for this service</dd> <dt><strong>handler.connectionLimitPerIP</strong></dt> <dd>Set the maximum simultaneous incoming connections per IP for this service</dd> + <dt><strong>auth.requireSSL</strong></dt> + <dd>Controls whether plaintext SASL mechanisms such as PLAIN require TLS. It defaults to true. + This setting applies to both the RFC 5034 AUTH command and the legacy USER/PASS commands.</dd> + <dt><strong>auth.plainAuthEnabled</strong></dt> + <dd>Controls whether PLAIN is available to AUTH. It defaults to true and does not disable the legacy USER/PASS commands.</dd> + <dt><strong>auth.saslMechanisms</strong></dt> + <dd>Optional ordered, comma-separated list of SASL mechanism factory class names for Guice applications. + Built-in factories can use simple names, for example PlainSaslMechanismFactory. Extensions use their fully qualified class name.</dd> <dt><strong>handler.handlerchain</strong></dt> <dd>This loads the core CommandHandlers. Only remove this if you really know what you are doing</dd> @@ -91,9 +99,12 @@ <dd>true or false - If true attemps a graceful shutdown, which is safer but can take time. Defaults to true.</dd> </dl> + <p>James implements the RFC 5034 AUTH command and advertises currently available mechanisms through CAPA as + <strong>SASL mechanism ...</strong>. The initial AUTH command is limited to 255 octets. SASL continuation lines support + up to 65,536 bytes. Negotiated SASL integrity and privacy layers are not supported.</p> + </section> </body> </document> - diff --git a/upgrade-instructions.md b/upgrade-instructions.md index efa37b07ff..22571c3b9d 100644 --- a/upgrade-instructions.md +++ b/upgrade-instructions.md @@ -20,6 +20,22 @@ Change list: - [Adding thread_id column to Postgresql email_query_view table](#adding-thread_id-column-to-postgresql-email_query_view-table) - [Lucene mailbox index schema update for collapseThreads support](#lucene-mailbox-index-schema-update-for-collapsethreads-support) - [JAMES-4210 SMTP AuthHook deprecation](#james-4210-smtp-authhook-deprecation) + - [JAMES-4210 POP3 USER/PASS requires TLS by default](#james-4210-pop3-userpass-requires-tls-by-default) + +### JAMES-4210 POP3 USER/PASS requires TLS by default + +Date: 16/07/2026 + +Concerned products: POP3 servers allowing USER/PASS authentication over clear-text connections + +POP3 USER/PASS authentication now follows the `auth.requireSSL` setting and requires TLS by default. Deployments that +intentionally allow clear-text USER/PASS authentication must add the following to each concerned `pop3server.xml` entry: + +```xml +<auth> + <requireSSL>false</requireSSL> +</auth> +``` ### JAMES-4210 SMTP AuthHook deprecation --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
