85.1.59. pepsi-helper-token-refresh

Refresh OAuth access tokens for the smarthost relay stage

Section du manuel:

1

85.1.59.1.1. Nom

pepsi-helper-token-refresh - garder à jour les jetons d’accès SASL OAuth (XOAUTH2 / OAUTHBEARER) du smarthost.

85.1.59.1.2. Synopsis

pepsi-helper-token-refresh [GLOBAL-OPTIONS]

pepsi-helper-token-refresh [GLOBAL-OPTIONS] –once

85.1.59.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 — frais à chaque remise — depuis le TOKEN_FILE de ce MTA. 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 — son jeton est supposé fourni par d’autres moyens.

C’est une implémentation d’un contrat de rafraîchissement externe ; 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.

85.1.59.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 est SGID au groupe pepsi-token (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 d’étape de relais smarthost est installé SGID pepsi-token, donnant au worker pepsi du dispatcher juste assez d’appartenance au groupe pour lire le jeton — et rien d’autre.

• Les jetons de rafraîchissement renouvelés (RFC 6749 §10.4 ; par exemple Microsoft) sont persistés dans un répertoire d’état privé ([pepsi-helper-token-refresh] STATE_DIR, par défaut /var/pepsi/token-refresh, mode 0700, jamais lisible par le groupe) et ont priorité sur le REFRESH_TOKEN configuré à la prochaine exécution. Les fichiers d’état eux-mêmes 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.

85.1.59.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). Un point de terminaison de jeton qui omet expires_in est réputé avoir émis un jeton d’une heure, et l’attente calculée ne descend jamais sous une minute, de sorte qu’un expires_in minuscule ne peut pas emballer la boucle. Une cible dont le rafraîchissement échoue est réessayée avec un back-off exponentiel tandis que son fichier de jeton précédent est laissé en place, de sorte qu’une panne transitoire du point de terminaison de jeton ne vide jamais un jeton fonctionnel. Il 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).

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

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

85.1.59.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 : 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.

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

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

85.1.59.1.11. Voir aussi

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

85.1.59.1.12. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.