Outlook/Exchange Authentication in Davmail

I have previously written an article about setting up Outlook/Exchange email on Linux, in which I discussed using davmail(1), a Java program that allows using a standard IMAP/SMTP interface to communicate with Outlook email. Not long after I wrote that article, Microsoft rolled out an update that broke it. In that article, I presented a davmail(1) 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(1) 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.

DavMail Configuration

To use manual authentication, set up your davmail(1) properties file as you normally would, using O365Manual for the mode. If you're just getting started with davmail(1), 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


# The ports to run the different services on. You'll need
# these to connect clients.
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(1) manually in a terminal. Be sure to leave this terminal open as you proceed to the next steps.

            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 
           

Email Client Configuration

Next, configure your email client of choice to connect to davmail(1). 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(1), as well as your usual username (probably your full email address) and password. If you haven't set up SSL/TLS for davmail(1), use unencrypted connections here. [1]

I personally use mbsync(1) for accessing my email and msmtp(1) for sending email, so here is what my configurations look like. 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"

Authenticating with Microsoft

Once you've configured your email client to use davmail(1), attempt to connect to the email server. This can usually be done by manually requesting an email synchronization. Using the configurations above, the command for this is,

            mbsync university
            

The email synchronization will block, and you should see an authentication prompt in your davmail(1) terminal,

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 will 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, copy and paste the entire URL from your browser into the davmail(1) terminal window, and hit enter. This will complete the authentication process. Don't worry if davmail(1) writes more text to the terminal between when you copy the URL and paste the new one in--this won't hurt anything. Ignore the new text and paste the URL anyway.

There are fairly good odds your email sync will have timed out by now. If it did, attempt to sync your email a second time. It should now work without any manual intervention.

If you examine your davmail(1) 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(1) 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.

Conclusion

And that is all there is to it. With a small amount of manual intervention every couple of weeks, you should be able to use a desktop email client with your Microsoft email account on Linux and BSD. I've been using this system for several years now, and it's been working quite reliably. The only downside is that davmail(1) is fairly slow compared to a native IMAP interface for email synchronization. But, this is a minor inconvenience, and I much prefer dealing with slower email syncs than using the Outlook web interface.