pizauth

Overview

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. Tokens are only ever stored in memory and are never persisted to disk.

Download and docs

• Latest release: pizauth-0.2.1 (2022-03-11)
  • Size: 44535 bytes (43KiB)
  • SHA256: OnN7xDgJ2x5lYeiVKpN7S5YPfiEkpbHOwpgxMTz01C0=
  • Release notes:
    
    • login_hint is now deprecated in favour of the more general auth_uri_fields. Change:

      "email@example.com";
      

      to:

      auth_uri_fields = { "login_hint": "email@example.com" };
      

      Currently login_hint is silently transformed into the equivalent auth_uri_fields for backwards compatibility.
    • auth_uri_fields allows users to specify zero or more key/value pairs to be appended to the authorisation URI. Keys (and their values) are appended in the order they appear in auth_uri_fields, each separated by a &. The same key may be specified multiple times.
    • Several options can now be set globally and overridden in individual accounts:
      • not_transient_error_if
      • refresh_at_least
      • refresh_before_expiry
      • refresh_retry
    • scopes is now optional and also, equivalently, can be empty.
  • 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\"";
  

  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.