Configure Mutt to work with OAuth 2.0

My email client of choice is mutt. The keyboard short-cuts are ingrained into muscle memory. I have tried to use complex passwords to keep myself secure. While that may help, many large web service providers require the use of OAuth 2.0 for better security.

The fine defenders of the galaxy at University of Glasgow IT started pushing for better security to access email and office365 applications. If Computer Scientists do not lead the way on these things, what hope is there for the rest of digital society?

Introduction

Peter van Ormondt wrote a simplified (for dummies) guide that even I could understand. It worked first time on Outlook365 and GMail. On GMail, I can now turn off "Less Secure Apps"¹ that annoyingly keeps getting switched off, if the method is not utilised regularly.

A better understanding of how OAuth 2.0 has been implemented is explained in the OAuth 2.0 documentation found in the mutt repo. While Mutt has native OAuth2 support, it provides a hook to an external script to provide the authentication details. Conveniently, the Mutt project themselves have provided a Python script mutt_oauth2.py to authorise the user. The script keeps local state on a file which can be used to refresh the token. The mutt_oauth2.py script keeps this encrypted using gpg.

Configuration

Configure and Authorise with mutt_oauth2.py

1. Create a separate gpg user to encrypt all the OAuth2 tokens for all providers. You could just as well re-use one of your other GPG keys for this.

   $ gpg --gen-key 
   GnuPG needs to construct a user ID to identify your key.
   
   Real name: My OAuth2 Token Encryption Key
   Email address: token.encryptor@oauth2.me
   You selected this USER-ID:
       "My OAuth2 Token Encryption Key <token.encryptor@oauth2.me>"
   
   Change (N)ame, (E)mail, or (O)kay/(Q)uit? O
   We need to generate a lot of random bytes. It is a good idea to perform
   some other action (type on the keyboard, move the mouse, utilize the
   disks) during the prime generation; this gives the random number
   generator a better chance to gain enough entropy.
   

2. Download and install mutt_oauth2.py

   $ curl -o /any-path/mutt_oauth2.py https://gitlab.com/muttmua/mutt/-/raw/master/contrib/mutt_oauth2.py?inline=false
   $ chmod u+x /any-path/mutt_oauth2.py
   

3. Replace YOUR_GPG_IDENTITY with your GPG key in mutt_oauth2.py

4. Our setup masquerades as the Mozilla Thunderbird e-mail client and utilizes their client-id and client-secret which is hard-coded into the client. The client secret is actually within the open-source repos of the Thunderbird client. You can also create your own credentials. See instructions for GMail. The Thunderbird client registration details as of today :

   • GMail: client-id - 406964657835-aq8lmia8j95dhl1a2bvharmfk3t1hgqj.apps.googleusercontent.com, client-secret - kSmqreRr0qwBWJgbf5Y-PjSU
   • Microsoft: client-id - 08162f7c-0fd2-4200-a84a-f25a4db0b584, client-secret - TxRBilcHdC6WGBee]fs?QR:SJ8nI[g82

5. Intial authorisation for this client should be executed as: /any-path/mutt_oauth2.py /any-path/oath2_token_file --authorize. There should be a separate file for each email provider. When requested to input authorisation flow or authentication method, localhostauthcode will store the file in the same path. This is a one time operation and will be valid as long as the oauth2_token_file is available. You can delete the file and do the authorisation again if you so desire. Executing this script will provide a URL to paste into a browser. After opening the link in the browser and finishing any requisite authorisation, the script will obtain a token, encrypt it with your GPG key and store it locally in the path you have chosen.

Configure .mutt config

Add the following entries to the .mutt config file for OAUTH2 authentication.

set imap_authenticators = "oauthbearer:xoauth2"
set imap_oauth_refresh_command = "/any-path/mutt_oauth2.py /any-path/oath2_token_file"
set smtp_authenticators = ${imap_authenticators}
set smtp_oauth_refresh_command = ${imap_oauth_refresh_command}

xoauth2 was the experimental authentication protocol which got standardised as oauthbearer. However, it seems that while GMail seems to work with oauthbearer, Microsoft still requires xoauth2.

Roll your own Client credentials for GMail

1. Login to your google account, and navigate to your developer console to generate OAuth 2.0 credentials
2. Navigate to the "Credentials" page and click on + Create Credentials to create an OAuth client ID.

This client-ID and client-secret can then be used in the mutt_oauth2.py script.