PIZAUTH(1) General Commands Manual PIZAUTH(1) NAME pizauth -- OAuth2 authentication daemon SYNOPSIS pizauth command 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 ac- count. 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 af- fected 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 encryp- tion on the output so that your data cannot be compromised. info [-j] Writes output about pizauth to stdout including: the cache direc- tory 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 incom- patible changes are made, this integer will be monotonically in- creased. 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 configu- ration: 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 re- voking a token: revoke thus only affects the local pizauth in- stance. 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 un- less -d is specified. Exits with 0 if the server started success- fully 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 in- clude an authorization URL. Note that this command does not block: commands must expect that they might encounter an error when show- ing 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 com- mand returns. status Writes output about the current accounts and whether they have ac- cess tokens to stdout. The format is human-readable and in an un- specified 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/ FreeBSD ports 15.quarterly September 13, 2022 PIZAUTH(1)
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=pizauth&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>