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_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.

SEE ALSO

pizauth(1)

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

AUTHORS

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