80. pepsi-helper-token-refresh

Refresh OAuth access tokens for the smarthost relay stage.

80.1. Role

A smarthost MTA configured with AUTH = oauth (see pepsi-stage-relay-to-smarthost) authenticates with a SASL bearer token the relay stage reads, fresh per delivery, from a TOKEN_FILE. Those access tokens are short-lived, so the file must be refreshed out of band.

pepsi-helper-token-refresh does that: for every [pepsi-stage-relay-to-smarthost-mta-<name>] with AUTH = oauth it pairs the MTA’s TOKEN_FILE/USERNAME with a secret section [pepsi-helper-token-refresh-<name>] (the OAuth client credentials, kept in a separate @inline-secret@ file readable only by this service), requests a fresh token from the provider’s TOKEN_ENDPOINT, and writes it atomically to the token file. GRANT selects the RFC 6749 grant: refresh_token (the default, e.g. Google; it also requires REFRESH_TOKEN) or client_credentials (e.g. Microsoft 365 app-only; it requires SCOPE); CLIENT_ID and CLIENT_SECRET are required either way. A rotated refresh token is persisted to the private [pepsi-helper-token-refresh] STATE_DIR (default /var/pepsi/token-refresh). A target whose secret section has no TOKEN_ENDPOINT is skipped, on the assumption that its token is provided out of band.

It is not a stage and is deliberately not part of pepsi.target — it is one implementation of the external refresh contract described in Extending the Pipeline, and a site may substitute its own. Reference: pepsi-helper-token-refresh(1).

80.2. Security

The service runs as the dedicated pepsi-helper-token-refresh account, the sole reader of the client secrets. It writes token files into a directory that is SGID the pepsi-token group (default /var/pepsi/tokens), mode 0640; the relay stage binary is installed SGID pepsi-token so the dispatcher’s pepsi worker can read them. See Extending the Pipeline for the full contract.

80.3. Modes

  • service (the default) — a long-lived process that refreshes each token proactively, ahead of expiry by REFRESH_MARGIN (default 5 min), retrying a failing target with back-off while leaving its previous token in place. Runs until SIGINT/SIGTERM.

  • –once — refresh every target a single time and exit (a manual run, a systemd timer, or cron); non-zero exit if any target failed.

80.4. See also

pepsi-stage-relay-to-smarthost, pepsi-setup, pepsi-helper-token-refresh(1), pepsi.conf(5).