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 le CLIENT_SECRET et le REFRESH_TOKEN ne sont jamais exposés à l’étape de relais (qui s’exécute en tant que pepsi) 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ême pepsi.conf sans erreur.

  • Les fichiers de jeton d’accès sont écrits dans un répertoire qui appartient au groupe pepsi-token et 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 mode 0640. Le binaire de l’étape de relais smarthost est installé SGID pepsi-token, ce qui donne au worker pepsi du 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_TOKEN configuré à la prochaine exécution. Ce répertoire est [pepsi-helper-token-refresh] STATE_DIR (par défaut /var/pepsi/token-refresh, mode 0700, jamais lisible par le groupe), et les fichiers d’état qu’il contient sont en mode 0600.

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, debug ou trace (par défaut : [pepsi] LOG, sinon info).

-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 --once a 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 que root sans le compte pepsi-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.