PIZAUTH.CONF(5)

📦
version 1.1.1 · 2 versions
, in nixpkgs unstable

💅 PIZAUTH.CONF(5) 💅

okay bestie, welcome to the pizauth.conf page — it's a File Formats Manual entry, section 5, and honestly it's giving "small file, big job". Let's get into it 🫶

✨ NAME ✨

pizauth.conf — the configuration file for pizauth(1). that's it. that's the name. iconic minimalism 💖

🎀 DESCRIPTION 🎀

pizauth.conf is the configuration file for pizauth(1). periodt.

🌸 the top-level options

these are the big-girl options that live at the top of the file, not inside any account block. slay.

  • auth_notify_cmd = "shell-cmd"; — names a shell command that gets run via $SHELL -c whenever an account needs to be authenticated. two special env vars get set for it: $PIZAUTH_ACCOUNT is set to the account name, and $PIZAUTH_URL is set to the URL required to authorise the account. heads up tho: auth_event_cmd is subject to a 10 second timeout. Optional. Optional. (yes it really says optional twice, and honestly? she's committed 💀)
  • auth_notify_interval = time; — the gap between reminders to the user about authentication requests. defaults to 15 minutes if you don't specify it. no cap.
  • error_notify_cmd = "shell-cmd"; — names a shell command run via $SHELL -c when an error has occurred when authenticating an account. two special env vars: $PIZAUTH_ACCOUNT is set to the account name, and $PIZAUTH_MSG is set to the error message. if you don't specify it, it defaults to logging via syslog(3).
  • http_listen = none | "bind-name"; — the address the pizauth(1) HTTP server listens on. if you say none, the HTTP server is turned off entirely. ⚠️ note: 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"; — the address the pizauth(1) HTTPS server listens on. if you say none, the HTTPS server is turned off entirely. ⚠️ same rule: at least one of the HTTP and HTTPS servers must be turned on. defaults to "127.0.0.1:0".
  • refresh_at_least = time; — the maximum period of time before an access token will be forcibly refreshed. defaults to 90 minutes if not specified. forcibly!! she said what she said 🔥
  • refresh_before_expiry = time; — how far in advance an access token should be refreshed before it expires. defaults to 90 seconds if not specified.
  • refresh_retry = time; — the gap between retrying a refresh after transitory errors (think: network problems being network problems 😭). defaults to 40 seconds if not specified.
  • startup_cmd = "shell-cmd"; — a shell command run via $SHELL -c after pizauth's server has completed setup and is ready to accept commands. ⚠️ note that unless -d is set, startup_cmd will be run after pizauth(1) has daemonised — which means the command will thus be run with stdin and stdin closed. (yes, stdin twice. we love a typo moment 🙈)
  • token_event_cmd = "shell-cmd"; — a shell command run via $SHELL -c when an account's access token changes state. two special env vars: $PIZAUTH_ACCOUNT is set to the account name, and $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. also note: token_event_cmd is subject to a 10 second timeout. Optional.

  • transient_error_if_cmd = "shell-cmd"; — a shell command run when pizauth repeatedly encounters errors trying to refresh a token. one special env var is set: $PIZAUTH_ACCOUNT is set to the account name. here's the vibe check 👑: 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 reauthenticate. if you don't specify it, it defaults to ignoring non-fatal errors.

🦋 the account block options

an account block supports the following options. these are the ones that live inside the block, iykyk:

  • 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" }; — 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"; — the OAuth2 client ID (i.e. the identifier of the client software). Mandatory.
  • client_secret = "Secret"; — the OAuth2 client secret (similar to the client_id). Optional.
  • login_hint = "Hint"; — 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"]; — zero or more OAuth2 scopes (roughly speaking, "permissions") that access tokens will give you permission to utilise. Optional.
  • token_uri = "URI"; — a URI specifying the OAuth2 server's token URI. Mandatory.

🧚 how times work

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. cute, right? 🍓

🌈 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. don't skip it bestie, it will not work and you will be sad 😭

🦋 SEE ALSO 🦋

👑 AUTHORS 👑

pizauth(1) was written by Laurence Tratt https://tratt.net/laurie/ — we stan a legend 💜

and that's the whole page, bestie! this one's from the Debian edition, dated September 13, 2022 — go forth and configure, you absolute main character 🌟💖✨

📦 where this page comes from