95.1.65. pepsi-helper-token-refresh¶
Refresh OAuth access tokens for the smarthost relay stage
- Section du manuel:
1
95.1.65.1.1. Nom¶
pepsi-helper-token-refresh - garder à jour les jetons d’accès SASL OAuth (XOAUTH2 / OAUTHBEARER) du smarthost.
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¶
Lorsqu’un MTA smarthost est configuré avec AUTH = oauth (voir pepsi-stage-relay-to-smarthost(1)), l’étape de relais s’authentifie avec un jeton porteur SASL qu’elle lit depuis le TOKEN_FILE de ce MTA, à nouveau à chaque remise. Les jetons d’accès OAuth sont à courte durée de vie (typiquement une heure), de sorte que quelque chose doit remplacer le contenu du fichier avant l’expiration de chaque jeton.
pepsi-helper-token-refresh est ce quelque chose. Pour chaque section [pepsi-stage-relay-to-smarthost-mta-<name>] avec AUTH = oauth, il cherche une section secrète correspondante [pepsi-helper-token-refresh-<name>] contenant les identifiants client OAuth, demande un jeton d’accès frais au point de terminaison de jeton du fournisseur, et l’écrit atomiquement dans le TOKEN_FILE de ce MTA. Un MTA OAuth sans section secrète correspondante lisible est sauté avec un avertissement : le programme suppose alors que son jeton est fourni par d’autres moyens.
C’est une implémentation d’un contrat externe qui régit le rafraîchissement des jetons ; un site peut substituer son propre équivalent (voir le chapitre Étendre le pipeline du manuel Pepsi). Il ne fait délibérément pas partie de pepsi.target et doit être activé explicitement.
95.1.65.1.4. Modèle de sécurité¶
Le service s’exécute en tant que le compte dédié non privilégié pepsi-helper-token-refresh et est le seul lecteur des secrets client OAuth :
Les sections secrètes par cible résident dans un fichier séparé inclus dans la configuration principale avec la directive taler
@inline-secret@(voir pepsi.conf(5)). Ce fichier n’est lisible que par ce compte, de sorte que leCLIENT_SECRETet leREFRESH_TOKENne sont jamais exposés à l’étape de relais (qui s’exécute en tant quepepsi) ni aux autres utilisateurs.@inline-secret@est silencieusement sauté pour un lecteur qui ne peut ouvrir le fichier, de sorte que l’étape de relais analyse le mêmepepsi.confsans erreur.Les fichiers de jeton d’accès sont écrits dans un répertoire qui appartient au groupe
pepsi-tokenet porte le bit SGID (par défaut/var/pepsi/tokens), de sorte que chaque fichier de jeton hérite de ce groupe et est créé en mode0640. Le binaire de l’étape de relais smarthost est installé SGIDpepsi-token, ce qui donne au workerpepsidu dispatcher juste assez d’appartenance au groupe pour lire le jeton — et rien d’autre.Lorsqu’un fournisseur renouvelle les jetons de rafraîchissement (RFC 6749 §10.4 ; par exemple Microsoft), le nouveau jeton est enregistré dans un répertoire d’état privé et a priorité sur le
REFRESH_TOKENconfiguré à la prochaine exécution. Ce répertoire est[pepsi-helper-token-refresh] STATE_DIR(par défaut/var/pepsi/token-refresh, mode0700, jamais lisible par le groupe), et les fichiers d’état qu’il contient sont en mode0600.
Démarré en tant que root, le processus abandonne d’abord ses privilèges vers le compte pepsi-helper-token-refresh ; il refuse de s’exécuter en tant que root. Les identifiants ne sont envoyés que via HTTPS : un TOKEN_ENDPOINT qui n’est pas une URL https:// fait échouer le rafraîchissement de cette cible au lieu d’envoyer le secret client en clair.
95.1.65.1.5. Modes¶
Sans indicateur, pepsi-helper-token-refresh s’exécute comme un service de longue durée. Chaque jeton est rafraîchi indépendamment et de façon proactive, avec REFRESH_MARGIN d’avance sur son expiration déclarée (cinq minutes par défaut). Si un point de terminaison de jeton omet expires_in, le service suppose qu’il a émis un jeton d’une heure, et l’attente calculée ne descend jamais sous une minute : un expires_in minuscule ne peut donc pas faire tourner le rafraîchissement en boucle serrée. Une cible dont le rafraîchissement échoue est réessayée avec un back-off exponentiel, et son fichier de jeton précédent reste en place ; une brève panne du point de terminaison de jeton n’efface donc jamais un jeton qui fonctionne. Le service s’exécute jusqu’à recevoir SIGINT ou SIGTERM.
Avec –once, chaque cible configurée est rafraîchie une seule fois et le processus quitte — la forme pour une exécution manuelle, un timer systemd, ou cron. Le code de sortie est non nul si une cible a échoué (après que toutes ont été tentées).
95.1.65.1.6. Configuration¶
Les cibles sont dérivées de la configuration du relais smarthost ; chacune associe une section MTA à une section secrète. Voir pepsi.conf(5) pour la référence complète des options. En résumé
# 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
Pour une cible Microsoft 365 application seule, utilisez GRANT = client_credentials avec SCOPE au lieu d’un REFRESH_TOKEN.
95.1.65.1.7. Options¶
- –once
Rafraîchir chaque cible configurée une fois et quitter, au lieu de s’exécuter comme un service qui rafraîchit avant l’expiration.
95.1.65.1.8. Options globales¶
Ces options peuvent apparaître avant ou après les autres indicateurs.
- -c FILE, –config FILE
Lit la configuration depuis FILE au lieu de parcourir les emplacements par défaut.
- -L LOGLEVEL, –log LOGLEVEL
Règle la verbosité de journalisation. LOGLEVEL est l’un de
error,warn,info,debugoutrace(par défaut :[pepsi] LOG, sinoninfo).- -v, –verbose
Affiche les messages de journal de toutes les sources, y compris les bibliothèques tierces.
- -h, –help
Affiche un résumé d’utilisation et quitte.
- -V, –version
Affiche la version et quitte.
95.1.65.1.9. Code de sortie¶
- 0
Achèvement réussi (une exécution
--oncea rafraîchi chaque cible, ou le service s’est arrêté proprement sur un signal).- 1
Une erreur s’est produite : une configuration malformée, une section secrète à laquelle manque une option requise, au moins une cible en échec en mode
--once, ou une tentative d’exécution en tant querootsans le comptepepsi-helper-token-refresh.
95.1.65.1.10. Exemples¶
Exécuter comme un service (le déploiement typique)
systemctl enable --now pepsi-helper-token-refresh.service
Rafraîchir chaque jeton une fois, à la main
pepsi-helper-token-refresh -c /etc/pepsi/pepsi.conf --once
95.1.65.1.11. Voir aussi¶
pepsi-stage-relay-to-smarthost(1), pepsi-setup(1), pepsi.conf(5)
95.1.65.1.12. Bogues¶
Signalez les bogues au gestionnaire de tickets de Pepsi.