Home > Software e-mail: laurie@tratt.net   twitter: laurencetratt   twitter: laurencetratt
email updates:
  |   RSS feed



pizauth is a simple program for requesting, showing, and refreshing OAuth2 access tokens. pizauth is formed of two components: a persistent server which interacts with the user to request tokens, and refreshes them as necessary; and a command-line interface which can be used by programs such as fdm, neomutt, or msmtp to authenicate with OAuth2. Tokens are only ever stored in memory and are never persisted to disk.

Download and docs

Quick setup and use

pizauth's configuration file is ~/.config/pizauth.conf. You need to specify at least one account, which tells pizauth how to authenticate against a particular OAuth2 setup. At a minimum you need to find out from your provider: For example, to create an account called officesmtp which obtains OAuth2 tokens which allow you to read email via IMAP and send email via Office365's servers:
account "officesmtp" {
  auth_uri = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
  token_uri = "https://login.microsoftonline.com/common/oauth2/v2.0/token";
  client_id = "..."; // Fill in with your Client ID
  client_secret = "..."; // Fill in with your Client secret
  scopes = [
  // You don't have to specify login_hint, but it does make
  // authentication a little easier.
  login_hint = "email@example.com";
The man page for pizauth.conf contains the complete list of configuration options.

You then need to run the pizauth server:

$ pizauth server
and configure software to request OAuth2 tokens with pizauth show officesmtp. The first time that pizauth show officesmtp is executed, it will print an error to stderr that includes an authorisation URL:
$ pizauth show officesmtp
ERROR - Token unavailable until authorised with URL https://login.microsoftonline.com/common/oauth2/v2.0/authorize?access_type=offline&code_challenge=xpVa0mDzvR1Ozw5_cWN43DsO-k5_blQNHIzynyPfD3c&code_challenge_method=S256&scope=https%3A%2F%2Foutlook.office365.com%2FIMAP.AccessAsUser.All+https%3A%2F%2Foutlook.office365.com%2FSMTP.Send+offline_access&client_id=&redirect_uri=http%3A%2F%2Flocalhost%3A14204%2F&response_type=code&state=%25E6%25A0%25EF%2503h6%25BCK&client_secret=&login_hint=email@example.com
The user then needs to open that URL in the browser of their choice and complete authentication. Once complete, pizauth will be notified, and shortly afterwards pizauth show officesmtp will start showing a token on stdout:
$ pizauth show officesmtp
Note that:
  1. pizauth show does not block: if a token is not available it will fail; once a token is available it will succeed.
  2. pizauth show can print OAuth2 tokens which are no longer valid. By default, pizauth will continually refresh your token, but it may eventually become invalid. There will be a delay between the token becoming invalid and pizauth realising that has happened and notifying you to request a new token.

Asynchronous notifications

OAuth2 (re)authentication can occur at any point. pizauth allows you to run arbitrary shell commands with the auth_notify_cmd global setting. The shell command will be run with two environment variable set: $PIZAUTH_ACCOUNT is the account name; and $PIZAUTH_URL. For example, to open authentication URLs up in your default browser:
auth_notify_cmd = "open \"$PIZAUTH_URL\"";
Calling notify-send on XFCE (and using sed to transform '&' to '&' to work around a flaw in the HTML parser of XFCE's notify daemon):
auth_notify_cmd = "notify-send -t 30000 'pizauth authorisation' \"<a href=\\\"`echo $PIZAUTH_URL | sed 's/&/&amp;/g'`\\\">$PIZAUTH_ACCOUNT</a>\"";
The auth_error_cmd allows you to run arbitrary shell commands when authentication errors occur. It sets two environment variables: $PIZAUTH_ACCOUNT is the account name; and $PIZAUTH_MSG is the error message.
Home > Software e-mail: laurie@tratt.net   twitter: laurencetratt twitter: laurencetratt