GERONIMO-6780 - Accept the reference implementation's OAuth2 configuration keys XOAUTH2 was only reachable through mail.<protocol>.sasl.enable together with mail.<protocol>.sasl.mechanisms, so an application moving here from the reference implementation had to be reconfigured to authenticate at all. Accept the keys it uses instead: mail.<protocol>.auth.mechanisms=XOAUTH2 mail.<protocol>.auth.xoauth2.disable=false auth.mechanisms is honoured as an alias of sasl.mechanisms, restricting which mechanisms are considered; the SASL-specific key still wins where both are set. XOAUTH2 needs no SASL API of its own, so it is now selected outside the sasl.enable branch and constructed directly rather than reflectively. It is only ever chosen when the application asked for it and the server advertises it, since the mechanism needs an access token rather than a password. SMTP, POP3 and NNTP already reached the factory unconditionally. IMAP gated XOAUTH2 behind sasl.enable, so it gets an attempt after the SASL block and before the PLAIN and LOGIN fallbacks. The existing sasl.enable configuration keeps working unchanged. The fake IMAP server used by the tests advertised AUTH=XOAUTH rather than AUTH=XOAUTH2; it now advertises both, matching what Gmail and Outlook offer, because selection checks the server capabilities.
Apache Geronimo Mail - Apache's implementation of the Jakarta Mail 2.1 specification (Jakarta EE 10). It passes the Jakarta Mail 2.1 TCK. The artifacts run on Java 11+ (building requires JDK 21, see below).
To build you will need:
The produced artifacts target Java 11, so they can be used on Java 11+ runtimes.
To build all changes incrementally:
mvn install
To perform clean builds, which are sometimes needed after some changes to the source tree:
mvn clean install
geronimo-mail_2.1_spec - the Jakarta Mail 2.1 API classes (org.apache.geronimo.specs:geronimo-mail_2.1_spec)geronimo-mail_2.1_impl/geronimo-mail_2.1_provider - the SMTP/IMAP/POP3/NNTP protocol providersgeronimo-mail_2.1_impl/geronimo-mail_2.1_mail - the merged all-in-one bundle most consumers want (org.apache.geronimo.mail:geronimo-mail_2.1_mail)geronimo-mail_2.1_tck - runs the Jakarta Mail TCK (see below); inactive in normal buildsThe implementation passes the Jakarta Mail 2.1 TCK (321/321). To run it locally (JDK 21 required - the TCK harness does not work on JDK 24+):
mvn clean install mvn verify -Ptck -pl geronimo-mail_2.1_tck
The profile downloads the TCK from download.eclipse.org, boots an embedded Apache James server and fails the build on any test failure. A nightly GitHub Actions workflow (tck.yml) runs the same thing. Known issue: Apache James 3.9 has a response write race that can make exactly one fetch test per run fail with Unknown server response: ) - re-run in that case. Details and manual/debugging instructions: geronimo-mail_2.1_impl/tck.adoc.
See RELEASE.md.
By default, parameter values in structured headers such as Content-Type and Content-Disposition must be quoted when they contain whitespace or special characters, as the MIME specification requires. Some real-world senders emit unquoted values (e.g. Content-Type: multipart/related; type=text/html; boundary=...), which then fail to parse. Setting the System property
mail.mime.parameters.strict=false
makes reading tolerant: an unquoted parameter value then simply ends at the next semicolon. The default is true (strict).
XOAUTH2 is supported for SMTP, IMAP, POP3 and NNTP. Because the mechanism needs an access token rather than a password, it is never selected on its own: the application has to ask for it, and the server has to advertise it.
Either of the two properties the reference implementation uses will do that:
mail.<protocol>.auth.mechanisms=XOAUTH2 mail.<protocol>.auth.xoauth2.disable=false
Pass the access token where the password would otherwise go, for example store.connect(host, user, accessToken).
mail.<protocol>.auth.mechanisms also restricts which mechanisms are considered in general, not only XOAUTH2. Note that it restricts but does not reorder: apart from XOAUTH2, which is tried first when it has been asked for, the remaining mechanisms are still selected strongest first (DIGEST-MD5, CRAM-MD5, LOGIN, PLAIN). Where both it and the older mail.<protocol>.sasl.mechanisms are set, the SASL-specific one wins, and the earlier mail.<protocol>.sasl.enable plus mail.<protocol>.sasl.mechanisms combination continues to work unchanged.
By default, the implementation checks for the presence of ssl.protocols. If this property is not set, the SSL/TLS socket is created with JVM defaults.
The property ssl.protocols can be used to specify a list of protocols, which should be enabled for the underlying SSL/TLS socket. It accepts a list of protocols with a whitespace as delimiter.
To support TLSv1+ the following property can be set:
mail.smtp.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2 TLSv1.3
The property ssl.socketFactory.class can be used to specify a custom SSL socket factory, which is used to create the underlying SSL/TLS socket. This allows full control of supported cyphers or protocols.
mail.smtp.ssl.socketFactory.class=my.custom.CustomSSLSocketFactory
The property ssl.socketFactory can be used to specify a pre-configured custom SSL socket factory, which is used to create the underlying SSL/TLS socket. In this context, the instance has to be passed to the Properties of the related MailSession. This allows full control of supported cyphers or protocols.
By default, the implementation checks for the presence of ssl.ciphersuites. If this property is not set, the SSL/TLS socket is created with all supported ciphers of the given SSL Socket.
The property ssl.ciphersuites can be used to specify a list of ciphers, which should be enabled for the underlying SSL/TLS socket. It accepts a list of ciphers with a whitespace as delimiter. You have to ensure, that the listed cipher suites are supported by the given JVM.
To support only TLS_AES_128_GCM_SHA256 and TLS_AES_256_GCM_SHA384 the following property can be set:
mail.smtp.ssl.ciphersuites=TLS_AES_128_GCM_SHA256 TLS_AES_256_GCM_SHA384
The property ssl.socketFactory.class can be used to specify a custom SSL socket factory, which is used to create the underlying SSL/TLS socket. This allows full control of supported cyphers or protocols.
mail.smtp.ssl.socketFactory.class=my.custom.CustomSSLSocketFactory
The property ssl.socketFactory can be used to specify a pre-configured custom SSL socket factory, which is used to create the underlying SSL/TLS socket. In this context, the instance has to be passed to the Properties of the related MailSession. This allows full control of supported cyphers or protocols.