pizauth

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 authenticate with OAuth2.

Download and docs

Latest release: pizauth-1.0.6 (2024-11-10)

• Size: 61827 bytes (60.38 KiB)
• SHA256: ZOuaZv0YWA7Dza56mGx8k0eTUetbI+VCPbK3Rfwumj8=
• Release notes:

All releases

Repository (issues, PRs, etc.)

Man pages for the latest release:

• pizauth(1)
• pizauth.conf(5)

Recipes for using pizauth with other software and services

Alternative programs

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:

• The authorisation URI.
• The token URI.
• Your “Client ID” (and in many cases also your “Client secret”), which identify your software. Some providers allow you to create client IDs and secrets at will.
• (In some cases) The scope(s) which your OAuth2 access token will give you access to. For pizauth to be able to refresh tokens, you may need to add an explicit offline_access scope.
• (In some cases) The redirect URI. The default value of http://localhost/ suffices in most instances.

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 = [
    "https://outlook.office365.com/IMAP.AccessAsUser.All",
    "https://outlook.office365.com/SMTP.Send",
    "offline_access"
  ];
  // You don't have to specify login_hint, but it does make
  // authentication a little easier.
  auth_uri_fields = {"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
DIASSPt7jlcBPTWUUCtXMWtj9TlPC6U3P3aV6C9NYrQyrhZ9L2LhyJKgl5MP7YV4

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\"";

If you only want authentication URLs to open if you explicitly request so, you can use external tools like notify-send to do so:

auth_notify_cmd = "if [[ \"$(notify-send -A \"Open $PIZAUTH_ACCOUNT\" -t 30000 'pizauth authorisation')\" == \"0\" ]]; then open \"$PIZAUTH_URL\"; fi";

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.

Persistence

By design, pizauth stores tokens state only in memory, and never to disk: users never have to worry that unencrypted secrets may be accessible on disk. However, if you use pizauth on a machine where pizauth is regularly restarted (e.g. because the machine is regularly rebooted), reauthenticating each time can be frustrating.

pizauth dump (which writes pizauth’s internal token state to stdout) and pizauth restore (which restores previously dumped token state read from stdin) allow you to persist state, but since they contain secrets they inevitably increase your security responsibilities. Although the output from pizauth dump may look like it is encrypted, it is trivial for an attacker to recover secrets from it: it is strongly recommended that you immediately encrypt the output from pizauth dump to avoid possible security issues.

The most common way to call pizauth dump is via the token_event_cmd configuration setting. token_event_cmd is called each time an account’s tokens change state (e.g. new tokens, refreshed tokens, etc). You can use this to run an arbitrary shell command such as pizauth dump:

token_event_cmd = "pizauth dump | age --encrypt --output pizauth.age -R age_public_key";

In this example, output from pizauth dump is immediately encrypted using Age. In your machine’s startup process you can then call pizauth restore to restore the most recent dump e.g.:

age --decrypt -i age_private_key -o - pizauth.age | pizauth restore

Note that pizauth restore does not change the running pizauth’s configuration. Any changes in security relevant configuration between the dumping and restoring pizauth instances cause those parts of the dump to be silently ignored.