John Heidemann / Other Stuff / Free Unix / OAuth2 for Getmail

This webpage documents support for OAuth2 on getmail6.

OAuth2 is an authentication scheme for EMail providers (Google GMail, Microsoft Outlook, etc.). Enterprises like it because they can lock it down and that makes them feel warm and fuzzy.

Using Configured Getmail6 getmail-gmail-xoauth-tokens

Create a provider.json file.

For google, it will be:

{"scope": "https://mail.google.com/",
 "user": "xxx-you@example.com",
 "client_id": "xxx.apps.googleusercontent.com",
 "client_secret": "xxx-foo",
 "token_uri": "https://accounts.google.com/o/oauth2/token",
 "auth_uri": "https://accounts.google.com/o/oauth2/auth",
 "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
 "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs"}

For Microsoft (O365), it will be:

{
  "user": "xxx-you@example.com",
  "scope": "offline_access https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/POP.AccessAsUser.All https://outlook.office.com/SMTP.Send",
  "client_id": "xxx-id-big-uuid",
  "client_secret": "xxx-secret-big-charstring",
  "tenant": "common",
  "auth_uri": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
 	  "token_uri": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
 	  "redirect_uri": "http://localhost:10101"
}

For some other provider, you have to figure out all of these values. Thunderbird has a long list of providers (go open source!) that may prove helpful.

In both cases you must fill in the xxx parts. The e-mail address is easy, but you also need to get the client_id and client_secret as described below in bootstrapping.

Start by running:

getmail-gmail-xoauth-tokens -i ~/.provider.json

It will print out a URL. Put that in your browser. Your browser will do 2FA (or not if you’re already known) and then redirect to http://localhost:10101/?code=xxx&session=yyy This redirect will fail, BUT you can cut-and-paste the URL and extract the xxx part (the code) and enter that in the getmail-gmail-xoauth-tokens program. After you do this you should see an access_token and a refresh_token in your (now rewriten) JSON file.

Then you will use a getmailrc file something like:

[retriever]
username = xxx-you@example.com
use_xoauth2 = True
password_command = ("/usr/bin/getmail-gmail-xoauth-tokens", "/home/xxx-you/provider.json")
type = SimpleIMAPSSLRetriever
server = outlook.office365.com

[desination]
type = Maildir
path = ~/Mail/

(edit the username and password_command)

After 90 days you will probably have to redo the -i to refresh the long-term (refresh) token.

(Thanks to James Prescott for catching an omission in my example.)

Bootstrapping Getmail6’s getmail-gmail-xoauth-tokens

One must do two difficult things before any of this works: (1) get client_id and client_secret, (2) get your enterprise e-mail admins to accept your client_id.

These values are specific for each e-mail provider, and e-mail software.

(Client-id is basically like a browser UserAgent string, but acquired through from e-mail provider.)

Getting Client-Id

Some options:

  1. Each e-mail program should ship with them. Thunderbird already does. Mutt has chosen not to. Getmail6 currently does not, so try the next option.

  2. The proper way to get one is to register as a developer. See the documentation in Mutt. It’s painful, but possible. Your secret will timeout after some duration, so you will need to refresh it.

  3. Although the id and secret are specific to a program, for testing, you may find it helpful to use them from another program.

  4. Please note that your client-id have to be approved for use by your organization, as desecribed next.

Getting Your E-Mail Admins to Accept It

For enterprises, OAuth2 providers must opt in every single e-mail program (each client_id).

So send your client_id to your admins and ask nicely. Have fun.

Background

Some pointers:

Copyright © 2022 by John Heidemann