Outlook/Exchange Authentication in DavMail

I have previously written an article on setting up Outlook/Exchange email on Linux, in which I discussed setting up DavMail, a Java program that allows you to use a standard IMAP/SMTP interface to communicate with Outlook email. Unfortunately, not long after I wrote that article, Microsoft rolled out an update that broke it. In that article, I presented a DavMail configuration that uses Basic Authentication, which was at the time the lowest friction approach to authentication. Unfortunately, Microsoft has now disabled support for basic authentication.

Thankfully, the fix isn’t complicated, although it does require a little bit more work. DavMail has support for several different authentication modes, which can be set by adjusting the davmail.mode property in the configuration file. The relevant values here are O365Modern for “modern” authentication, or O365Manual for manual authentication.

I don’t know if it is down to me not using it correctly, or the way Penn State configures its email, but I cannot get O365Modern to work. Instead, I use O365Manual. It isn’t nearly as much of a pain as you might expect.

To use manual authentication, set up your DavMail properties file as you normally would, using O365Manual for the mode. If you’re just getting started with DavMail, here is a simple configuration to get you started,

# Disallow access to the davmail server from remote hosts (i.e., other
# computers on the network)
davmail.allowRemote=false

# Don't use SSL (between email client and davmail)
davmail.ssl.nosecurecaldav=false
davmail.ssl.nosecureimap=false
davmail.ssl.nosecureldap=false
davmail.ssl.nosecuresmtp=false

# Ports to run the different services on. You'll need these to connect
# your clients. If you have several Exchange accounts, each one will need
# to run on different ports
davmail.caldavPort=5000
davmail.imapPort=5001
davmail.ldapPort=5002
davmail.smtpPort=5003

# Connection details for your exchange account. Odds are good that the
# url listed here will work for you. If not, see if your University/employer
# has any details on the correct host URL to connect to their email services
# with.
davmail.url=https://outlook.office365.com/EWS/Exchange.asmx

# Set the authentication mode to manual
davmail.mode=O365Manual

# Run davmail in server mode
davmail.server=true
davmail.enableKeepAlive=true

With your configuration file set up, run DavMail manually in a terminal,

$ davmail <path to configuration file>
2022-12-24 16:37:35,829 INFO  [main] davmail  - DavMail Gateway 6.0.1-3390 listening on SMTP port 5003 IMAP port 5001 CALDAV port 5000 LDAP port 5002 

Next, configure your email client of choice to connect to DavMail. Use 127.0.0.1 has the hostname for IMAP and SMTP (this special IP address indicates localhost, the same computer running the email client), and give it the ports that you’ve used from your configuration file for DavMail, as well as your usual username (probably your full email address) and password. If you haven’t set up SSL/TLS, be sure to use unencrypted connections¹ here.

I personally use mbsync(1) for accessing my email and msmtp(1) for sending email, so here is what my configurations look like, where get-pass is a wrapper script to the pass(1) password manager that I use (and can be found here).

mbsync config

IMAPAccount university
Host 127.0.0.1
Port 1143
UserCmd "get-pass -c email/psu email"
PassCmd "get-pass -c email/psu"
SSLType None
AuthMechs LOGIN

IMAPStore university-remote
Account university

MaildirStore university-local
Subfolders Verbatim
Path ~/.local/share/mail/university/
Inbox ~/.local/share/mail/university/Inbox

Channel university
Far :university-remote:
Near :university-local:
SyncState *
Patterns *
Create Both
Sync All
Expunge Near

msmtp config:

account university
host 127.0.0.1
port 1025
protocol smtp
auth plain
tls off
user <YOUR EMAIL ADDRESS HERE>
from <YOUR EMAIL ADDRESS HERE>
passwordeval "get-pass email/psu"

Once these are configured, attempt to connect to the email server. In my case, with mbsync(1), this is done with,

$ mbsync university

The email synchronization will block, and you should see an authentication prompt in your DavMail output, something like this

Please open the following link: 
https://login.microsoftonline.com/common/oauth2/authorize?<...>
 proceed through authentication steps and paste back the final url that contains authentication code (blank page)
Authentication code: 

Copy and paste the provided URL into your web browser, and you should be presented with an Office365 login screen, or possibly with a blank white screen if you are already authenticated with Office365 in your browser. If you don’t get a white screen right away, complete your sign on as usual, after which you should get the white screen.

Once you’re on the white screen, simply copy and paste the entire URL from your browser into the DavMail terminal window, and hit enter. This will complete the authentication process.

There’s fairly good odds your email sync will have timed out by now. So go ahead and repeat the process. This time, you should get let in without any manual intervention.

If you examine your DavMail configuration file again, you should see a new entry called davmail.oauth.<email>.refreshToken. This is the token that you retrieved during the manual sign-on process above.

The token will remain valid for some time (I don’t know precisely how long, but it is on the order of weeks in my experience), during which you can automatically authenticate with Outlook even if your DavMail is running as a service in the background. If at some point your authentication fails randomly, it is likely that the token has expired, in which case you only need to repeat the above process to get a new token.

And that’s it! With a little bit of manual intervention every couple of weeks, you should be able to get access to your Microsoft Outlook/Exchange email on Linux and BSD. DavMail has, in my experience, been pretty reliable, if a good bit slower than a direct IMAP connection. But, so far as I am concerned, slow but working is better than not working at all!

I hope that you found this information useful. Happy emailing!