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:
-
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.
-
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.
-
Although the id and secret are specific to a program, for testing, you may find it helpful to use them from another program.
-
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:
- OAuth2 on Mutt: greatly recommended theory (and some discussion about a per-program
client_id
). - XOauth2 on getmail-5.6
- Thunderbird supports OAuth2: see UWM screenshots or the relevant source