85.1.59. pepsi-helper-token-refresh

Refresh OAuth access tokens for the smarthost relay stage

Handbuchabschnitt:

1

85.1.59.1.1. Name

pepsi-helper-token-refresh - die SASL-OAuth-Zugriffstokens (XOAUTH2 / OAUTHBEARER) für den Smarthost aktuell halten.

85.1.59.1.2. Übersicht

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

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

85.1.59.1.3. Beschreibung

Wenn ein Smarthost-MTA mit AUTH = oauth konfiguriert ist (siehe pepsi-stage-relay-to-smarthost(1)), authentifiziert sich die Relay-Stage mit einem SASL-Bearer-Token, das sie — bei jeder Zustellung frisch — aus der TOKEN_FILE dieses MTA liest. OAuth-Zugriffstokens sind kurzlebig (typischerweise eine Stunde), daher muss etwas den Inhalt der Datei ersetzen, bevor jedes Token abläuft.

pepsi-helper-token-refresh ist dieses Etwas. Für jeden [pepsi-stage-relay-to-smarthost-mta-<name>]-Abschnitt mit AUTH = oauth sucht es einen passenden Geheimnis-Abschnitt [pepsi-helper-token-refresh-<name>], der die OAuth-Client-Zugangsdaten enthält, fordert ein frisches Zugriffstoken vom Token-Endpunkt des Anbieters an und schreibt es atomar in die TOKEN_FILE dieses MTA. Ein OAuth-MTA ohne lesbaren passenden Geheimnis-Abschnitt wird mit einer Warnung übersprungen — es wird angenommen, dass sein Token auf andere Weise bereitgestellt wird.

Es ist eine Implementierung eines externen Refresh-Vertrags; ein Standort kann sein eigenes Äquivalent einsetzen (siehe das Kapitel Die Pipeline erweitern des Pepsi-Handbuchs). Es ist bewusst nicht Teil von pepsi.target und muss ausdrücklich aktiviert werden.

85.1.59.1.4. Sicherheitsmodell

Der Dienst läuft als das dedizierte unprivilegierte Konto pepsi-helper-token-refresh und ist der einzige Leser der OAuth-Client-Geheimnisse:

  • Die Geheimnis-Abschnitte pro Ziel liegen in einer separaten Datei, die mit der Taler-Direktive @inline-secret@ in die Hauptkonfiguration eingebunden wird (siehe pepsi.conf(5)). Diese Datei ist nur für dieses Konto lesbar, sodass das CLIENT_SECRET und das REFRESH_TOKEN nie der Relay-Stage (die als pepsi läuft) oder anderen Benutzern offengelegt werden. @inline-secret@ wird für einen Leser, der die Datei nicht öffnen kann, stillschweigend übersprungen, sodass die Relay-Stage dieselbe pepsi.conf ohne Fehler parst.

  • Die Zugriffstoken-Dateien werden in ein Verzeichnis geschrieben, das SGID auf die pepsi-token-Gruppe ist (Standardwert /var/pepsi/tokens), sodass jede Token-Datei diese Gruppe erbt und mit Modus 0640 erstellt wird. Das Smarthost-Relay-Stage-Binärprogramm wird SGID pepsi-token installiert und gibt dem pepsi-Worker des Dispatchers gerade genug Gruppenmitgliedschaft, um das Token zu lesen — und nichts anderes.

  • Rotierte Refresh-Tokens (RFC 6749 §10.4; z. B. Microsoft) werden in einem privaten Zustandsverzeichnis persistiert ([pepsi-helper-token-refresh] STATE_DIR, Standardwert /var/pepsi/token-refresh, Modus 0700, nie gruppenlesbar) und haben beim nächsten Lauf Vorrang vor dem konfigurierten REFRESH_TOKEN. Die Zustandsdateien selbst haben Modus 0600.

Als root gestartet, gibt der Prozess seine Privilegien zunächst an das Konto pepsi-helper-token-refresh ab; er weigert sich, als root zu laufen. Zugangsdaten werden nur über HTTPS gesendet.

85.1.59.1.5. Modi

Ohne Flag läuft pepsi-helper-token-refresh als langlebiger Dienst. Jedes Token wird unabhängig und proaktiv erneuert, um REFRESH_MARGIN (Standardwert fünf Minuten) vor seinem angegebenen Ablauf. Bei einem Token-Endpunkt, der expires_in weglässt, wird angenommen, dass er ein Token mit einer Stunde Gültigkeit ausgestellt hat, und die berechnete Wartezeit fällt nie unter eine Minute, sodass ein winziges expires_in die Schleife nicht durchdrehen lassen kann. Ein Ziel, dessen Erneuerung fehlschlägt, wird mit exponentiellem Backoff wiederholt, während seine vorherige Token-Datei an Ort und Stelle bleibt, sodass ein vorübergehender Ausfall des Token-Endpunkts nie ein funktionierendes Token leert. Es läuft, bis es SIGINT oder SIGTERM empfängt.

Mit –once wird jedes konfigurierte Ziel einmalig erneuert und der Prozess beendet sich — die Form für einen manuellen Lauf, einen systemd-Timer oder Cron. Der Exit-Status ist ungleich null, wenn irgendein Ziel fehlschlug (nachdem alle versucht wurden).

85.1.59.1.6. Konfiguration

Die Ziele werden aus der Smarthost-Relay-Konfiguration abgeleitet; jedes paart einen MTA-Abschnitt mit einem Geheimnis-Abschnitt. Siehe pepsi.conf(5) für die vollständige Optionsreferenz. Im Überblick:

# 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

Für ein reines App-Ziel bei Microsoft 365 verwenden Sie GRANT = client_credentials mit SCOPE statt eines REFRESH_TOKEN.

85.1.59.1.7. Optionen

–once

Erneuert jedes konfigurierte Ziel einmal und beendet sich, statt als Dienst zu laufen, der vor Ablauf erneuert.

85.1.59.1.8. Globale Optionen

Diese Optionen können vor oder nach den anderen Flags stehen.

-c FILE, –config FILE

Liest die Konfiguration aus FILE, statt die Standardorte zu durchsuchen.

-L LOGLEVEL, –log LOGLEVEL

Setzt die Log-Ausführlichkeit. LOGLEVEL ist eines von error, warn, info, debug oder trace (Standardwert: info).

-v, –verbose

Zeigt Log-Meldungen aus allen Quellen, einschließlich Drittanbieter-Bibliotheken.

-h, –help

Gibt eine Verwendungsübersicht aus und beendet sich.

-V, –version

Gibt die Version aus und beendet sich.

85.1.59.1.9. Exit-Status

0

Erfolgreicher Abschluss (ein --once-Lauf erneuerte jedes Ziel, oder der Dienst fuhr auf ein Signal hin sauber herunter).

1

Ein Fehler ist aufgetreten: eine fehlerhafte Konfiguration, ein Geheimnis-Abschnitt, dem eine erforderliche Option fehlt, mindestens ein im --once-Modus fehlschlagendes Ziel oder ein Versuch, als root ohne das pepsi-helper-token-refresh-Konto zu laufen.

85.1.59.1.10. Beispiele

Als Dienst ausführen (die typische Installation):

systemctl enable --now pepsi-helper-token-refresh.service

Jedes Token einmal von Hand erneuern:

pepsi-helper-token-refresh -c /etc/pepsi/pepsi.conf --once

85.1.59.1.11. Siehe auch

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

85.1.59.1.12. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.