95.1.65. pepsi-helper-token-refresh¶
Refresh OAuth access tokens for the smarthost relay stage
- Manual section:
1
95.1.65.1.1. Name¶
pepsi-helper-token-refresh - keep the smarthost SASL OAuth (XOAUTH2 / OAUTHBEARER) access tokens current.
95.1.65.1.2. Synopsis¶
pepsi-helper-token-refresh [GLOBAL-OPTIONS]
pepsi-helper-token-refresh [GLOBAL-OPTIONS] –once
95.1.65.1.3. Description¶
When a smarthost MTA is configured with AUTH = oauth (see
pepsi-stage-relay-to-smarthost(1)), the relay stage authenticates with a
SASL bearer token that it reads from that MTA’s TOKEN_FILE, afresh for
every delivery. OAuth access tokens are short-lived (typically one hour), so
something must replace the file’s contents before each token expires.
pepsi-helper-token-refresh is that something. For every
[pepsi-stage-relay-to-smarthost-mta-<name>] section with AUTH = oauth it
looks for a matching secret section [pepsi-helper-token-refresh-<name>]
holding the OAuth client credentials, requests a fresh access token from the
provider’s token endpoint, and writes it atomically to that MTA’s TOKEN_FILE.
An OAuth MTA with no readable matching secret section is skipped with a warning,
on the assumption that its token is supplied by other means.
It is one implementation of an external contract for refreshing tokens; a
site may substitute its own equivalent (see the Extending the Pipeline
chapter of the Pepsi manual). It is deliberately not part of
pepsi.target and must be enabled explicitly.
95.1.65.1.4. Security model¶
The service runs as the dedicated unprivileged account
pepsi-helper-token-refresh and is the only reader of the OAuth client
secrets:
The per-target secret sections live in a separate file included into the main configuration with the taler
@inline-secret@directive (see pepsi.conf(5)). That file is readable only by this account, so theCLIENT_SECRETandREFRESH_TOKENare never exposed to the relay stage (which runs aspepsi) or to other users.@inline-secret@is silently skipped for a reader that cannot open the file, so the relay stage parses the samepepsi.confwithout error.The access-token files are written into a directory that belongs to the
pepsi-tokengroup and has the SGID bit set (default/var/pepsi/tokens), so each token file inherits that group and is created mode0640. The smarthost relay stage binary is installed SGIDpepsi-token, giving the dispatcher’spepsiworker just enough group membership to read the token — and nothing else.When a provider rotates refresh tokens (RFC 6749 §10.4; e.g. Microsoft), the new refresh token is saved in a private state directory and takes precedence over the configured
REFRESH_TOKENon the next run. That directory is[pepsi-helper-token-refresh] STATE_DIR(default/var/pepsi/token-refresh, mode0700, never group-readable), and the state files in it are mode0600.
Started as root, the process first drops to the
pepsi-helper-token-refresh account; it refuses to run as root.
Credentials are sent only over HTTPS: a TOKEN_ENDPOINT that is not an
https:// URL fails that target’s refresh instead of sending the client
secret in cleartext.
95.1.65.1.5. Modes¶
With no flag, pepsi-helper-token-refresh runs as a long-lived service.
Each token is refreshed independently and proactively, ahead of its stated
expiry by REFRESH_MARGIN (default five minutes). A token endpoint that omits
expires_in is assumed to have issued a one-hour token, and the computed wait
never falls below one minute, so a tiny expires_in cannot make the service
refresh in a tight loop. A target whose refresh fails is retried with
exponential back-off while its previous token file is left in place, so a short
outage of the token endpoint never erases a working token. The service runs
until it receives SIGINT or SIGTERM.
With –once, every configured target is refreshed a single time and the process exits — the form for a manual run, a systemd timer, or cron. The exit status is non-zero if any target failed (after all were attempted).
95.1.65.1.6. Configuration¶
The targets are derived from the smarthost relay configuration; each pairs an MTA section with a secret section. See pepsi.conf(5) for the full option reference. In outline:
# main pepsi.conf (world-readable):
[pepsi-stage-relay-to-smarthost-mta-gmail]
HOST = smtp.gmail.com
PORT = 587
MODE = starttls
AUTH = oauth
USERNAME = me@example.com
TOKEN_FILE = /var/pepsi/tokens/gmail
CATCH_ALL = YES
@inline-secret@ pepsi-helper-token-refresh-gmail /etc/pepsi/secrets/token-refresh.conf
# /etc/pepsi/secrets/token-refresh.conf (readable only by the refresher):
[pepsi-helper-token-refresh-gmail]
TOKEN_ENDPOINT = https://oauth2.googleapis.com/token
GRANT = refresh_token
CLIENT_ID = ...
CLIENT_SECRET = ...
REFRESH_TOKEN = ...
# REFRESH_MARGIN = 5 m
For an app-only Microsoft 365 target use GRANT = client_credentials with
SCOPE instead of a REFRESH_TOKEN.
95.1.65.1.7. Options¶
- –once
Refresh every configured target once and exit, instead of running as a service that refreshes ahead of expiry.
95.1.65.1.8. Global Options¶
These options may appear before or after the other flags.
- -c FILE, –config FILE
Read the configuration from FILE instead of searching the default locations.
- -L LOGLEVEL, –log LOGLEVEL
Set the logging verbosity. LOGLEVEL is one of
error,warn,info,debugortrace(default:[pepsi] LOG, elseinfo).- -v, –verbose
Show log messages from all sources, including third-party libraries.
- -h, –help
Print a usage summary and exit.
- -V, –version
Print the version and exit.
95.1.65.1.9. Exit Status¶
- 0
Successful completion (a
--oncerun refreshed every target, or the service shut down cleanly on a signal).- 1
An error occurred: a malformed configuration, a secret section missing a required option, at least one target failing in
--oncemode, or an attempt to run asrootwithout thepepsi-helper-token-refreshaccount.
95.1.65.1.10. Examples¶
Run as a service (the typical deployment):
systemctl enable --now pepsi-helper-token-refresh.service
Refresh every token once, by hand:
pepsi-helper-token-refresh -c /etc/pepsi/pepsi.conf --once
95.1.65.1.11. See Also¶
pepsi-stage-relay-to-smarthost(1), pepsi-setup(1), pepsi.conf(5)
95.1.65.1.12. Bugs¶
Report bugs to the Pepsi issue tracker.