Michele Marcionelli - Head of IT at D-MATH

Mutt with OAuth2 configuration

For instance this works for outlook.com accounts and also for ethz.ch accounts which are already in "Exchange Online".


Install GnuPG

OAuth works with secret tokens and these need to be encripted with GnuPG; install it as follow:

# Fedora Linux
sudo dnf install gnupg2
# Ubuntu Linux
sudo apt-get install gnupg
# macOS with MacPorts
sudo port install gnupg2
# macOS with Homebrew
sudo brew install gnupg

Generate a key pair

gpg --gen-key
Real name: Michele Marcionelli
Email address: mima-test@ethz.ch
Change (N)ame, (E)mail, or (O)kay/(Q)uit? ==> confirm with "O"
Enter a passphare to protect you new key: **********

IMPORTANT: do not forget this password; you are going to use it every time that you start mutt!

Install and configure mutt_oauth2.py

Download mutt_oauth2.py

[ ! -d ~/bin ] && mkdir ~/bin
cd bin
wget https://gitlab.com/muttmua/mutt/-/raw/master/contrib/mutt_oauth2.py
chmod +x mutt_oauth2.py

and configure it:

vi mutt_oauth2.py
ENCRYPTION_PIPE = ['gpg', '--encrypt', '--recipient', 'mima-test@ethz.ch']
registrations = {
    'microsoft': {
        'client_id': '9e5f94bc-e8a4-4e73-b8be-63364c29d753',

Note: The client_id for mutt seems not to exist, but it is not that important and we use the one from Thunderbird 9e5f94bc-e8a4-4e73-b8be-63364c29d753 and in this case the client_secret can be left empty. During the login process (see the next step), you will be notified you are trying to login via "Thunderbird".

Create an OAuth2 token file

mutt_oauth2.py ~/.my_mutt_oauth_token --verbose --authorize

OAuth2 registration: microsoft
Preferred OAuth2 flow: devicecode
Account e-mail address: mima-test@ethz.ch

To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code FUNCWGSYH to authenticate.

NOTICE: Obtained new access token, expires 2024-01-18T14:33:21.367816.
Access Token: ********************

Configure mutt with OAuth2

Configure mutt as follow:

set hostname                   = "ethz.ch"
set imap_user                  = "mima-test@ethz.ch"
set realname                   = "Michele Marcionelli"
set from                       = "${realname} <${imap_user}>"
set folder                     = "imaps://${imap_user}@outlook.office365.com"
set spoolfile                  = "+INBOX"
set smtp_url                   = "smtp://${imap_user}@smtp.office365.com:587"
set imap_authenticators        = "xoauth2"
set imap_oauth_refresh_command = "/path/to/bin/mutt_oauth2.py /path/to/.my_mutt_oauth_token"
set smtp_authenticators        = ${imap_authenticators}
set smtp_oauth_refresh_command = ${imap_oauth_refresh_command}
set ssl_force_tls              = "yes"
set ssl_starttls               = "yes"

and test the command defined in imap_oauth_refresh_command manually:

/path/to/bin/mutt_oauth2.py /path/to/.my_mutt_oauth_token

depending on how you installed GnuPG, you will maybe need to set this environment variable, but try without it first:

export GPG_TTY=$(tty)

See also