Outlook Oauth2 for VM

This page describes how to access Outlook mailboxes by IMAP using Oauth2 authentication. This is necessary because Microsoft are withdrawing the use of password authentication to access Outlook via what they arrogantly call "legacy protocols", i.e. non-proprietary protocols.

Security considerations

The oauth2 tokens, which give access to your email (but not to anything else), are stored in your home directory in files named
.oauth2-outlook.office365.com:UUN@ed.ac.uk-{access,refresh}
These files must be kept secret. The helper script forces them to Unix mode rw-------, and DICE homedirs are protected. With the number of users, I don't think it's worth my while trying to add some kind of password protection for the tokens.

Please be aware that oauth2, especially Microsoft's version, is not very secure, and is easy to phish. Many phishing attacks abuse exactly the authentication mechanism I'm using here, by tricking you into entering the code into a malicious webpage. Be very careful with all such authentications.

Preliminaries

If you use VM, you presumably know it:) I assume you are using a reasonably recent version of VM, such as the one installed for Emacs on DICE.

If you download your mail from Outlook to DICE using VM, you will have lines in your .vm looking something like this:

(setq vm-spool-files
       (list (concat "imap-ssl:outlook.office365.com:993:INBOX:login:"
               (user-real-login-name) "@ed.ac.uk" ":*")))

(setq vm-spool-files
       (list "imap-ssl:outlook.office365.com:993:INBOX:login:jcb@ed.ac.uk:*"))

(setq vm-spool-files 
	'(
          ("imap-ssl:outlook.office365.com:993:INBOX:login:jcb@ed.ac.uk:*"
	  )
 )

or some such variation. The only bit relevant now is the word login in the fifth field of the mailbox definition.

To use oauth2, you need two files:

If you use VM on DICE, you can just use my copies of the files, as shown below. (I recommend this, in case I have to fix bugs.) If you use VM on another system, or prefer to make your own copies, then install them in an appropriate place.

Set-up

To convert to oauth2, you need to make the following changes to your .vm:

Add the following line:
```
(load-library "/home/jcb/lib/emacs/vm/vm-imap-oauth2")
```
or the equivalent for where you put your own copy.
If you are not on DICE, or are using your own copies of the files, add a line of the form
```
(setq vm-imap-oauth2-helper "/home/jcb/lib/oauth2-helper")
```
adapted appropriately. (This is the default location, so not needed if you're using my files.)

Change the word login in the mailbox spec to oauth2, for example

(setq vm-spool-files 
	'(
          ("imap-ssl:outlook.office365.com:993:INBOX:oauth2:jcb@ed.ac.uk:*"
	  )
 )

Usage

The first time you log in to the mailbox, Emacs will show a window with instructions. If you're running under X, it will (or should) open a browser window to the relevant URL; otherwise, you should visit the given URL in a browser on your local computer, phone or whatever. Enter the code shown in the Emacs window into the browser, and follow instructions. Sign in as UUN@ed.ac.uk as usual. You will be told that you are signing into ed.ac.uk imap (by jcb). When this process is complete, go back to Emacs (remembering to click in the minibuffer if you copied the code with the mouse under X!) and press Return in the minibuffer.

You will have to go through this palaver every 90 days, or if you do not log in for 14 days. On the positive side, you will no longer have to type your password every time you start VM.

Julian Bradfield

Last modified: Thu Sep 8 17:42:50 BST 2022