Configure Confluence SMTP with TLS via JNDI for Office 365 Relay

Comments

or

How To Fix: javax.net.ssl.SSLException: Unrecognized SSL message, plaintext connection in Confluence JNDI

I’ve been doing Exchange to Office 365 migrations lately and that means on-premises applications and devices can’t use the local Exchange server to send mail anymore.

Your options are to use the credentials of an Office 365 mailbox to send mail, set up a local SMTP relayer, or use a third-party SMTP service.

If you’ve opted to use an Office 365 login to send mail via SMTP, then you must use TLS, so the applications/devices sending mail must support sending mail with TLS on port 587.

This article focuses on Atlassian Confluence but may apply to other java applications using JNDI to configure mail.

Atlassian Confluence, Secure SMTP, and JNDI

Confluence has no way to set up secure SMTP with SSL or TLS from within the administration, so unfortunately you’re forced to configure Confluence to use a JNDI Location for SMTP. This involves moving around JARs and changing configuration files, which will end up slowing down your upgrades (see my script to make Confluence upgrades easier).

Start with the existing GMail configuration:

Most of what you need is already written for using gmail, but gmail uses SSL on SMTP, and these exact settings will fail if you use it with SMTP that starts plain and changes to secure with STARTTLS.

If you use it directly, you’ll get an error like you see at the top of the article:

javax.net.ssl.SSLException: Unrecognized SSL message, plaintext connection

This is because the existing settings include this line:

mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"

That line specifically forces SSL to be used, so you end up trying to connect to an SMTP server expecting plain text, and sending encrypted data to it so it doesn’t know what you’re talking about.

Removing that line is all you need to do differently aside from changing the SMTP host, port, etc. So if you’ve done those steps, you don’t need what you see below.

Step by Step

The entire process (mostly copied from the above article) goes like this:

  1. Stop Confluence.

  2. Move (don’t copy) activation-1.0.2.jar and mail-1.4.1.jar from <confluence-install>/confluence/WEB-INF/lib to <confluence-install>/lib.
    Note: The version numbers on these jar files may vary, but that should not matter.
    As of Confluence 5.2.3, activation-1.0.2.jar no longer exists, and does not need to be moved or downloaded.

  3. Add the following to your server.xml file found in <confluence-install>/conf/ (add it just before the </Context> tag – This is the modified version for Office 365):
    <Resource name="mail/Office365"
auth="Container"
type="javax.mail.Session"
mail.smtp.host="smtp.office365.com"
mail.smtp.port="587"
mail.smtp.auth="true"
mail.smtp.user="[email protected]"
password="yourPassword"
mail.smtp.starttls.enable="true"
mail.transport.protocol="smtps"
/>

  4. Restart Confluence.

  5. Choose the cog icon cog icon at top right of the screen, then choose Confluence Admin.

  6. Choose Mail Servers.

  7. Choose either Edit an existing configuration, or Add a new SMTP mail server.

  8. Edit the server settings as necessary, and set the JNDI Location as:
    java:comp/env/mail/Office365


    Note that the JNDI Location is case sensitive and must match the resource name specified in server.xml.

  9. Submit, and send a test email.

That should be it!

Using this info for a different application? Please tell me!

If you found this useful for something other than Confluence, I’m interested in hearing about it and probably listing it in the article.