NAME
pizauth.conf
—
pizauth configuration file
DESCRIPTION
pizauth.conf
is the configuration file for
pizauth(1).
The top-level options are:
- auth_notify_cmd = "shell-cmd";
- specifies a shell command to be run via ‘
$SHELL -c
’ when an account needs to be authenticated. Two special environment variables are set: $PIZAUTH_ACCOUNT is set to the account name; $PIZAUTH_URL is set to the URL required to authorise the account. Optional. - auth_notify_interval = time;
- specifies the gap between reminders to the user of authentication requests. Defaults to 15 minutes if not specified.
- error_notify_cmd = "shell-cmd";
- specifies a shell command to be run via ‘
$SHELL -c
’ when an error has occurred when authenticating an account. Two special environment variables are set: $PIZAUTH_ACCOUNT is set to the account name; $PIZAUTH_MSG is set to the error message. Defaults to logging via syslog(3) if not specified. - http_listen = "bind-name";
- specifies the address for the pizauth(1) HTTP server to listen on. Defaults to "127.0.0.1:0".
- transient_error_if_cmd = "shell-cmd";
- specifies a shell command to be run when pizauth repeatedly encounters errors when trying to refresh a token. One special environment variable is set: $PIZAUTH_ACCOUNT is set to the account name. If shell-cmd returns a zero exit code, the transient errors are ignored. If shell-cmd returns a non-zero exit code, or exceeds a 3 minute timeout, pizauth treats the errors as permanent: the access token is invalidated (forcing the user to later reauthenicate). Defaults to ignoring non-fatal errors if not specified.
- refresh_at_least = time;
- specifies the maximum period of time before an access token will be forcibly refreshed. Defaults to 90 minutes if not specified.
- refresh_before_expiry = time;
- specifies how far in advance an access token should be refreshed before it expires. Defaults to 90 seconds if not specified.
- refresh_retry = time;
- specifies the gap between retrying refreshing after transitory errors (e.g. due to network problems). Defaults to 40 seconds if not specified.
- token_event_cmd = "shell-cmd";
- specifies a shell command to be run via ‘
$SHELL -c
’ when an account's access token changes state. Two special environment variables are set: $PIZAUTH_ACCOUNT is set to the account name; $PIZAUTH_EVENT is set to the event type. The event types are: token_invalidated if a previously valid access token is invalidated; token_new if a new access token is obtained; token_refreshed if an access token is refreshed. Token events are queued and processed one-by-one in the order they were received: at most one instance of token_event_cmd will be executed at any point in time; and there is no guarantee that an event reflects the current state of an account's access token, since further events may be stored in the queue. Note that token_event_cmd is subject to a 10 second timeout. Optional.
An ‘account’ block supports the following options:
- auth_uri = "URI";
- where URI is a URI specifying the OAuth2 server's authentication URI. Mandatory.
- auth_uri_fields = { "Key 1": "Val 1", ..., "Key n": "Val n" };
- specifies zero or more query fields to be passed to
auth_uri after any fields that
pizauth.conf
may have added itself. Keys (and their values) are added to auth_uri in the order they appear in auth_uri_fields, each separated by "&". The same key may be specified multiple times. Optional. - client_id = "ID";
- specifies the OAuth2 client ID (i.e. the identifier of the client software). Mandatory.
- client_secret = "Secret";
- specifies the OAuth2 client secret (similar to the client_id). Optional.
- login_hint = "Hint";
- is used by the authentication server to help the user understand which
account they are authenticating. Typically a username or email address.
Optional.
Deprecated:
use ‘
auth_uri_fields = { "login_hint": "Hint" }
’ instead. - redirect_uri = "URI";
- where URI is a URI specifying the OAuth2 server's redirection URI. Defaults to "http://localhost/" if not specified.
- refresh_at_least = time;
- Overrides the global refresh_at_least option for this account. Follows the same format as the global option.
- refresh_before_expiry = time;
- Overrides the global refresh_before_expiry option for this account. Follows the same format as the global option.
- refresh_retry = time;
- Overrides the global refresh_retry option for this account. Follows the same format as the global option.
- scopes = ["Scope 1", ..., "Scope n"];
- specifies zero or more OAuth2 scopes (roughly speaking, "permissions") that access tokens will give you permission to utilise. Optional.
- token_uri = "URI";
- is a URI specifying the OAuth2 server's token URI. Mandatory.
Times can be specified as int [smhd] where the suffixes mean (in order): seconds, minutes, hours, days. For example, 90s means 90 seconds and 5m means 5 minutes.
EXAMPLES
An example pizauth.conf
file for accessing
IMAP and SMTP services in Office365 is as follows:
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" }; }
Note that Office365 requires the non-standard "offline_access" scope to be specified in order for pizauth(1) to be able to operate successfully.
SEE ALSO
AUTHORS
pizauth(1) was written by Laurence Tratt https://tratt.net/laurie/