90. pepsi-helper-token-refresh

Refresh OAuth access tokens for the smarthost relay stage.

90.1. Role

A smarthost MTA configured with AUTH = oauth (see pepsi-stage-relay-to-smarthost) authenticates with a SASL bearer token that the relay stage reads from a TOKEN_FILE, afresh for each delivery. 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>], requests a fresh token from the provider’s TOKEN_ENDPOINT and writes it atomically to the token file. The secret section holds the OAuth client credentials and is kept in a separate @inline-secret@ file that only this service can read. 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).

90.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. Rotated refresh tokens stay in the private STATE_DIR (mode 0700, files 0600), never in the group-readable token directory, and a TOKEN_ENDPOINT that is not https:// is refused. See Extending the Pipeline for the full contract and The privilege split for how the pepsi-token group fits the privilege split.

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

90.4. See also

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