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 = none | "bind-name";: specifies the address for the pizauth(1) HTTP server to listen on. If none is specified, the HTTP server is turned off entirely. Note that at least one of the HTTP and HTTPS servers must be turned on. Defaults to "127.0.0.1:0".
https_listen = none | "bind-name";: specifies the address for the pizauth(1) HTTPS server to listen on. If none is specified, the HTTPS server is turned off entirely. Note that at least one of the HTTP and HTTPS servers must be turned 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_revoked if the user has requested that any token, or ongoing authentication for, an account should be removed or cancelled. 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.

AUTHORS

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

NAME

DESCRIPTION

EXAMPLES

SEE ALSO

AUTHORS