95.1.65. pepsi-helper-token-refresh

Refresh OAuth access tokens for the smarthost relay stage

Handbuchabschnitt:

1

95.1.65.1.1. Name

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

95.1.65.1.2. Übersicht

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

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

95.1.65.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 aus der TOKEN_FILE dieses MTA liest, und zwar bei jeder Zustellung neu. 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; das Programm nimmt dann an, dass sein Token auf andere Weise bereitgestellt wird.

Es ist eine Implementierung eines externen Vertrags, nach dem Tokens erneuert werden; 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.

95.1.65.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 der Gruppe pepsi-token gehört und das SGID-Bit gesetzt hat (Standardwert /var/pepsi/tokens), sodass jede Token-Datei diese Gruppe erbt und mit Modus 0640 erstellt wird. Das Binärprogramm der Smarthost-Relay-Stage wird SGID pepsi-token installiert und gibt dem pepsi-Worker des Dispatchers gerade genug Gruppenmitgliedschaft, um das Token zu lesen — und nichts anderes.

  • Wenn ein Anbieter Refresh-Tokens rotiert (RFC 6749 §10.4; z. B. Microsoft), wird das neue Refresh-Token in einem privaten Zustandsverzeichnis gespeichert und hat beim nächsten Lauf Vorrang vor dem konfigurierten REFRESH_TOKEN. Dieses Verzeichnis ist [pepsi-helper-token-refresh] STATE_DIR (Standardwert /var/pepsi/token-refresh, Modus 0700, nie gruppenlesbar), und die Zustandsdateien darin 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: Ein TOKEN_ENDPOINT, der keine https://-URL ist, lässt die Aktualisierung dieses Ziels fehlschlagen, statt das Client-Geheimnis im Klartext zu senden.

95.1.65.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. Lässt ein Token-Endpunkt expires_in weg, wird angenommen, dass er ein Token mit einer Stunde Gültigkeit ausgestellt hat, und die berechnete Wartezeit fällt nie unter eine Minute. So kann ein winziges expires_in den Dienst nicht dazu bringen, in einer engen Schleife zu erneuern. Ein Ziel, dessen Erneuerung fehlschlägt, wird mit exponentiellem Backoff wiederholt, während seine vorherige Token-Datei an Ort und Stelle bleibt. Fällt der Token-Endpunkt kurz aus, wird daher nie ein funktionierendes Token gelöscht. Der Dienst läuft, bis er 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).

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

95.1.65.1.7. Optionen

–once

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

95.1.65.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: [pepsi] LOG, sonst 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.

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

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

95.1.65.1.11. Siehe auch

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

95.1.65.1.12. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.