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 untilSIGINT/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).