not_transient_error_if
has been removed as a global and
per-account option. In its place is a new global option
transient_error_if_cmd
.
If you have an existing not_transient_error_if
option, you will
need to reconsider the shell command you execute. One possibility is to
change:
not_transient_error_if = "shell-cmd";to:
transient_error_if_cmd = "! shell-cmd";
transient_error_if_cmd
sets the environment variable
$PIZAUTH_ACCOUNT
to allow you to perform different actions for
different accounts if you desire.~/.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:
offline_access
scope.
http://localhost/
suffices in most instances.
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 serverand 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=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&redirect_uri=http%3A%2F%2Flocalhost%3A14204%2F&response_type=code&state=%25E6%25A0%25EF%2503h6%25BCK&client_secret= &login_hint=email@example.com
pizauth show officesmtp
will start showing a token on stdout:
$ pizauth show officesmtp DIASSPt7jlcBPTWUUCtXMWtj9TlPC6U3P3aV6C9NYrQyrhZ9L2LhyJKgl5MP7YV4Note that:
pizauth show
does not block: if a token is not available it will fail;
once a token is available it will succeed.
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.
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/&/&/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.
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 restoreNote 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.