How to set up OAuth2 in the Mutt email client

Open Authorization 2.0 (OAuth2) is a protocol that lets an application or website use a resource that someone else controls. It enables secure delegated access to web resources by using access tokens to allow access rights. 

OAuth2 is how programs can access third-party applications without requiring authentication for each resource. Many web services use OAuth2, including Google and Facebook.

What is Mutt?

Mutt is a small and powerful Unix-based text email client with a long history. Mutt supports most mail formats and protocols, and there are many configurable options to define your own macros and key bindings. Although Mutt is highly customizable, for a long time, it lacked OAuth2 support. That became a challenge as OAuth2 became a more popular authentication method. However, since version 2.0, Mutt has adopted support for OAuth2.

This article assumes you're comfortable with Mutt's basic configuration and day-to-day use. The aim is to enhance your existing Mutt deployment with OAuth2 support to access a Gmail account.

Install Mutt and supporting packages

Install Mutt and the necessary packages with your package manager:

$ sudo dnf install mutt
$ sudo dnf install gpg
$ sudo dnf install pinentry
$ sudo dnf install python38

Note that Mutt needs Python for OAuth2 support. It also uses Gnu Privacy Guard (GPG):

• mutt_oauth2.py needs Python >= 3.7 to work, so python38 or python39 must be installed.
• GPG (in the default configuration) needs the pinentry package to generate keys.

[ There's no single way to install software on Linux. Learn your options by downloading this guide to installing applications on Linux. ]

Set up Mutt with Gmail using OAuth2

You can set up Mutt for any email provider, but this tutorial will use Gmail because is so commonly used.

There are several steps needed to configure Mutt with OAuth2 support and associate it with your Gmail account. You'll need to generate GPG keys, obtain Gmail credentials, and configure Mutt.

1. Generate keys

The first step is to generate GPG keys. Use the following command:

$ gpg --gen-key

2. Obtain credentials

Next, obtain the credentials for the Gmail account you intend to support. You can obtain your Gmail credentials from Google's console.

[ Writing scripts? Download the Bash shell scripting cheat sheet. ]

3. Configure Mutt

Next, set up Mutt to use OAuth2. Download the project. Then edit the mutt_oauth2.py file:

sed -i 's/urn:ietf:wg:oauth:2.0:oob/http:\/\/localhost:1\//g' mutt_oauth2.py

Then edit it manually with the following directives:

set your client_id and client_secret
set your GPG identity (your email address or whatever you picked above) in the ENCRYPTION_PIPE line
export GPG_TTY=$(tty)
./mutt_oauth2.py <token file - select path (eg. ~/.mytoken.token)> --verbose --authorize

The script asks a series of questions to complete the configuration. Go through the questions and provide the following information (tested and working choices):

google
authcode
type your email address
copy the link into the browser and allow access to your account
obtain code and paste it back into the script

Due to many updates in Google's systems, you might receive a "This site can't be reached" error. If this happens, copy your code from the error message:

"
This site can’t be reached
The web page at http://localhost:1/?code=4/0AX4XfWjam91La54C5Y9H2345etJvAMDmSiL9
L4S_da1f2HDT7R9cIekCXeVv2sxMDA&scope=https://mail.google.com/ might be temporarily
down or it may have moved permanently to a new web address.


ERR_UNSAFE_PORT

"

Test the token to ensure the authentication process works:

$ mutt_oauth2.py <token file> --verbose --test
$ mutt_oauth2.py <token file> --verbose --debug --test

Create a configuration file at ~/.mutt/muttrc file and insert following lines:

set realname = "test"
set from = "<your email address>@gmail.com"
set use_from = yes
set envelope_from = yes

set smtp_url = "smtps://<your email address>@gmail.com@smtp.gmail.com:465/"
set imap_user = "<your name>@gmail.com"
set folder = "imaps://imap.gmail.com:993"
set spoolfile = "+INBOX"
set ssl_force_tls = yes

# G to get mail
bind index G imap-fetch-mail
set editor = "vim"
set charset = "utf-8"
set record = ''
 set imap_authenticators="oauthbearer:xoauth2"
 set imap_oauth_refresh_command="<path to mutt_oauth2.py> <token file>"
 set smtp_authenticators=${imap_authenticators}
 set smtp_oauth_refresh_command=${imap_oauth_refresh_command}

Run Mutt

It's time to test the configuration. Mutt should be connected to your Gmail account, so you should be able to send and receive email messages through the command line.

Wrap up

If you're already a Mutt user, adding OAuth2 support is a significant enhancement. The configuration requires several steps, but you should now be prepared to set it up on your Linux system.

For more information, see:

• Mutt_oauth.py README
• Mutt's OAuth documentation