FreeBSD Manual Pages
PIZAUTH.CONF(5) File Formats Manual PIZAUTH.CONF(5) 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 ac- count needs to be authenticated. Two special environment vari- ables are set: $PIZAUTH_ACCOUNT is set to the account name; $PIZAUTH_URL is set to the URL required to authorise the ac- count. Optional. auth_notify_interval = time; specifies the gap between reminders to the user of authentica- tion 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 er- ror 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. De- faults 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 en- counters errors when trying to refresh a token. One special environment variable is set: $PIZAUTH_ACCOUNT is set to the ac- count name. If shell-cmd returns a zero exit code, the tran- sient 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 re- freshed before it expires. Defaults to 90 seconds if not spec- ified. 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 ac- count'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 invali- dated; 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 authenti- cation 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 to- ken, since further events may be stored in the queue. Note that token_event_cmd is subject to a 10 second timeout. Op- tional. An `account' block supports the following options: auth_uri = "URI"; where URI is a URI specifying the OAuth2 server's authentica- tion 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 ap- pear 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 under- stand which account they are authenticating. Typically a user- name 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 ac- count. 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 or- der): 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 success- fully. SEE ALSO pizauth(1) https://tratt.net/laurie/src/pizauth/ AUTHORS pizauth(1) was written by Laurence Tratt https://tratt.net/laurie/ FreeBSD Ports 14.quarterly September 13, 2022 PIZAUTH.CONF(5)
NAME | DESCRIPTION | EXAMPLES | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pizauth.conf&sektion=5&manpath=FreeBSD+Ports+14.3.quarterly>