NAME

pizauth — OAuth2 authentication daemon

SYNOPSIS

DESCRIPTION

pizauth requests, shows, and refreshes OAuth2 tokens. It is formed of two components: a persistent "server" which interacts with the user to obtain tokens, and refreshes them as necessary; and a command-line interface which can be used by other programs to show the OAuth2 token for a current account.

The top-level commands are:

dump

Writes the current pizauth state to stdout: this can later be fed back into pizauth with restore. The dump format is stable within a pizauth major release (but not across major releases) and stable across platforms, though it includes timestamps that may be affected by clock drift on either the machine performing dump or restore. Clock drift does not not affect security, though it may cause dumped access tokens to be refreshed unduly early or late upon a restore. Refreshed access tokens will then be refreshed at the expected intervals.

Note that while the dump output may look like it is encrypted, it is trivial for an attacker to recover access and refresh tokens from it: it is strongly recommended that you use external encryption on the output so that your data cannot be compromised.

info [-j]

Writes output about pizauth to stdout including: the cache directory path; the config file path; and pizauth version. Defaults to human-readable output in an unspecified format that may change freely between pizauth versions.

-j specifies JSON output. The "info_format_version" field is an integer value specifying the version of the JSON output: if incompatible changes are made, this integer will be monotonically increased.

refresh [-u] account

Request a refresh of the access token for account. Exits with 0 upon success. If there is not currently a valid access or refresh token, reports an error to stderr, initiates a new token request, and exits with 1. Unless -u is specified, the error will include an authorization URL. Note that this command does not block and will not start a new refresh if one is ongoing.

reload

Reload the server's configuration. Exits with 0 upon success or 1 if there is a problem in the configuration.

restore

Reads previously dumped pizauth state from stdin and updates those parts of the current state it determines to be less useful than the dumped state. This does not change the running instance's configuration: any changes in security relevant configuration between the dumping and restoring pizauth instances causes those parts of the dump to be silently ignored. See dump for information about the dump format, timestamp warnings, and encryption suggestions.

revoke account

Removes any token, and cancels any ongoing authentication, for account. Note that OAuth2 provides no standard way of remotely revoking a token: revoke thus only affects the local pizauth instance. Exits with 0 upon success.

server [-c config-file] [-dv]

Start the server. If not specified with -c, pizauth checks for the configuration file (in order) at: $XDG_CONFIG_HOME/pizauth.conf, $HOME/.config/pizauth.conf. The server will daemonise itself unless -d is specified. Exits with 0 if the server started successfully or 1 otherwise. -v enables more verbose logging. -v can be used up to 4 times, with each repetition increasing the quantity of logging.

show [-u] account

If there is an access token for account, print that access token to stdout and exit with 0. If there is not currently a valid access token, prints an error to stderr and exits with 1. If refreshing might obtain a valid access token, refreshing is initiated in the background. Otherwise (unless -u is specified), the error will include an authorization URL. Note that this command does not block: commands must expect that they might encounter an error when showing an access token.

shutdown

Shut the server down. Note that shutdown occurs asynchronously: the server may still be alive for a period of time after this command returns.

status

Writes output about the current accounts and whether they have access tokens to stdout. The format is human-readable and in an unspecified format that may change freely between pizauth versions.

SEE ALSO

pizauth.conf(5)

https://tratt.net/laurie/src/pizauth/

AUTHORS

pizauth was written by Laurence Tratt https://tratt.net/laurie/