Tran Hong Quan created JAMES-4210:
-------------------------------------
Summary: Generic SASL mechanism extension model for James protocols
Key: JAMES-4210
URL: https://issues.apache.org/jira/browse/JAMES-4210
Project: James Server
Issue Type: Improvement
Components: IMAPServer, POP3Server, sieve, SMTPServer
Affects Versions: 3.10
Reporter: Tran Hong Quan
I would like to propose a generic SASL mechanism extension model for James
protocols.
Today, when adding a new authentication mechanism for IMAP or SMTP, we need to
modify core protocol code, such as IMAP _AuthenticateProcessor_ or SMTP
{_}AuthCmdHandler{_}. This makes the protocol handlers accumulate
mechanism-specific branches, and would make future mechanisms such as GSSAPI /
Kerberos harder to add cleanly.
The goal is:
- adding a new SASL mechanism should not require modifying core IMAP/SMTP
command handlers;
- protocol code should keep protocol framing and side effects;
- SASL mechanism code should own mechanism semantics and exchange state;
- existing IMAP/SMTP behavior should remain unchanged when no new
configuration is provided.
This takes inspiration from JMAP authentication strategies configuration and
Guice loading.
*Configuration shape*
-------------------
Each protocol would keep an operator-visible _auth.saslMechanisms_ list.
Example for IMAP:
_<auth>_
_<saslMechanisms>PlainSaslMechanism,OauthBearerSaslMechanism,XOauth2SaslMechanism,com.example.james.kerberos.GssapiSaslMechanism</saslMechanisms>_
_</auth>_
Example for SMTP:
_<auth>_
_<saslMechanisms>LoginSaslMechanism,PlainSaslMechanism,OauthBearerSaslMechanism,XOauth2SaslMechanism,com.example.james.kerberos.GssapiSaslMechanism</saslMechanisms>_
_</auth>_
Expected semantics:
- if _auth.saslMechanisms_ is absent, load current protocol defaults;
- IMAP defaults remain PLAIN, OAUTHBEARER, XOAUTH2;
- SMTP defaults remain LOGIN, PLAIN, OAUTHBEARER, XOAUTH2;
- if configured, load the configured list in the configured order;
- simple class names resolve against James default SASL packages;
- fully qualified class names allow external/community extensions;
Existing protocol settings still decide availability. For example, plain auth
restrictions still decide whether PLAIN is advertised, OIDC configuration still
decides whether OAuth mechanisms are advertised, and SMTP _auth.announce_ still
controls whether SMTP advertises AUTH.
*Proposed SPI shape*
------------------
I propose introducing protocol-neutral SASL types in {_}protocols/api{_}, for
example under {_}org.apache.james.protocols.api.sasl{_}.
The core idea is a stateful SaslExchange: each SASL mechanism creates one
exchange per authentication attempt, and that exchange owns mechanism state
across the initial request and continuation responses.
Core structure:
_interface SaslMechanism {_
_String name();_
_boolean supports(SaslProtocol protocol);_
_boolean isAvailable(SaslSessionContext context);_
_SaslExchange start(SaslInitialRequest request, SaslSessionContext
context);_
_}_
_enum SaslProtocol {_
_IMAP, SMTP, MANAGESIEVE, POP3_
_}_
_record SaslInitialRequest(SaslProtocol protocol, String mechanismName,
Optional<byte[]> initialResponse) {_
_}_
_record SaslIdentity(Username authenticationId, Username authorizationId) {_
_}_
_interface SaslSessionContext {_
_SaslProtocol protocol();_
_boolean isTlsStarted();_
_<T> Optional<T> configuration(Class<T> configurationType);_
_}_
_interface SaslExchange extends AutoCloseable {_
_SaslStep firstStep();_
_SaslStep onResponse(byte[] clientResponse);_
_void abort();_
_@Override_
_void close();_
_}_
_interface SaslStep {_
_record Challenge(Optional<byte[]> payload) implements SaslStep {_
_}_
_record Success(SaslIdentity identity, Optional<byte[]> serverData,
String log) implements SaslStep {_
_}_
_record Failure(String log) implements SaslStep {_
_}_
_}_
The intended split is:
- SASL mechanisms own payload parsing, challenge generation, response
validation, final SASL identity extraction, and exchange state.
- IMAP/SMTP bridges own base64/wire framing, continuation responses,
success/failure session side effects, audit logs, hooks, and protocol-specific
error responses.
For example, PLAIN and OAUTHBEARER can complete from {_}firstStep(){_}, while
GSSAPI can return Challenge first and complete later from {_}onResponse(...){_}.
SaslIdentity carries both the authentication identity and the authorization
identity. This keeps delegation expressible by the SPI without granting it
automatically. IMAP/SMTP bridges still decide whether delegation is allowed and
how to build their protocol session state.
*Loading and registry*
--------------------
Mechanism loading would follow the same spirit as JMAP authentication
strategies:
_interface SaslMechanismLoader {_
_ImmutableList<SaslMechanism> load(Collection<String> classNames);_
_}_
_class SaslMechanismRegistry {_
_Optional<SaslMechanism> find(String mechanismName, SaslProtocol
protocol) {_
_// match by mechanism name and supports(protocol)_
_}_
_Stream<SaslMechanism> availableFor(SaslProtocol protocol,
SaslSessionContext context) {_
_// filter supports(protocol) and isAvailable(context)_
_}_
_}_
Then implement a GuiceSaslMechanismLoader to actually load the SASL mechanisms.
*Incremental implementation plan*
-------------------------------
I suggest doing this step by step:
- {_}Step 1{_}: Start with a POC introducing the shared SaslMechanism SPI and
adapting IMAP.
This must not introduce breaking changes to existing authentication configs.
The SASL SPI can be adopted gradually, protocol by protocol, without changing
behavior for protocols that have not adopted it yet.
- {_}Step 2{_}: Adapt SASL modularization for SMTP.
- {_}Step 3{_}: Leverage the SASL modularization to implement GSSAPI / Kerberos
mechanism support.
ManageSieve and POP3 are not part of the immediate scope, but the SPI should
make later adoption possible.
*Testing expectations*
--------------------
At minimum, I think we should prove:
- no breaking change: absent auth.saslMechanisms keeps existing IMAP/SMTP SASL
methods;
- configured custom SASL mechanism loads and authenticates through real or
near-real protocol wiring;
- authentication / authorization identity handling preserves existing
delegation behavior (we should already have tests for these);
- fake multi-step mechanism works for continuation;
- exchange cleanup is covered.
*Feedback requested*
------------------
Does this refactoring direction look reasonable to you? Feedback and discussion
are welcome!
Meanwhile, I would start POC work on my side to see how this design goes...
Regards,
Quan
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
