SMTPGraphRelay/README.md

SMTPGraphRelay

Lokaler SMTP Store-and-Forward Relay für Windows mit Versand über Microsoft 365 / Microsoft Graph.

SMTPGraphRelay nimmt klassische lokale SMTP-Mails von Druckern, Scannern, NAS, Servern, Monitoring-Systemen usw. entgegen und leitet sie per OAuth / Microsoft Graph an Microsoft 365 weiter.

Installation

Einfachste Variante

Windows PowerShell 5.1 als Administrator öffnen und diesen Befehl ausführen:

$u='https://me-gitea.maieredv.cloud/MAIEREDV/SMTPGraphRelay/raw/branch/main/Setup-SMTPGraphRelay.ps1';$f="$env:TEMP\Setup-SMTPGraphRelay.ps1";Invoke-WebRequest $u -UseBasicParsing -OutFile $f;& $f

Danach erscheint das SMTPGraphRelay-Verwaltungsmenü.

Der Installer lädt automatisch den aktuellen Stand aus dem Gitea-Repository und installiert SMTPGraphRelay nach:

C:\Program Files\SMTPGraphRelay

Es muss kein ZIP manuell heruntergeladen oder entpackt werden.

Installer / Manager

[1] Neuinstallation aus Gitea
[2] Installation aus Gitea reparieren
[3] Nach Online-Updates suchen
[4] Entra / Exchange RBAC prüfen
[5] Zertifikat erneuern
[6] Health Check ausführen
[7] Deinstallieren
[8] Status anzeigen
[0] Beenden

Was die Neuinstallation automatisch erledigt

• prüft Windows PowerShell 5.1
• installiert benötigte PowerShell-Module systemweit
• lädt die aktuellen Programmdateien aus Gitea
• installiert nach C:\Program Files\SMTPGraphRelay
• erzeugt ein nicht exportierbares Zertifikat in LocalMachine\My
• erstellt die Entra ID App Registration
• erstellt den Entra Service Principal
• vergibt keine globale Graph Mail.Send Application Permission
• richtet Exchange Online Application RBAC ein
• begrenzt Application Mail.Send auf das konfigurierte Absenderpostfach
• erzeugt config.json
• legt Queue-, Failed- und Log-Verzeichnisse an
• erstellt die Windows-Firewallregel
• erstellt den Scheduled Task unter SYSTEM
• startet SMTPGraphRelay
• führt abschließend den Health Check aus

Architektur

Drucker / Scanner / NAS / Server / Monitoring
                    |
                    | SMTP
                    v
             SMTPGraphRelay
                    |
                    | Queue / Retry
                    v
             Microsoft Graph
                    |
                    | OAuth2 App-only
                    v
              Microsoft 365

SMTP-Funktionen

• EHLO / HELO
• MAIL FROM
• mehrere RCPT TO
• DATA
• RSET
• NOOP
• QUIT
• IPv4-Netzwerk-Allowlist
• maximale Nachrichtengröße
• bis zu 20 parallele SMTP-Verbindungen standardmäßig
• konfigurierbares Parallel-Limit
• 421 Service busy bei erreichtem Parallel-Limit

Store-and-Forward Queue

queue\
├── incoming\
├── pending\
└── processing\

failed\

• Nachrichten werden zunächst atomar unter incoming geschrieben.
• Erst vollständig geschriebene Nachrichten werden unter pending sichtbar.
• Während des Graph-Versands liegen Nachrichten unter processing.
• Nach einem Absturz werden verbliebene Processing-Nachrichten wieder nach Pending gestellt.
• Permanent fehlgeschlagene Nachrichten landen unter failed.

Retry-Verhalten

• HTTP 429: Microsoft Retry-After wird berücksichtigt
• ohne Retry-After: exponentielles Backoff
• HTTP 408 und 5xx: Retry
• DNS-, TLS-, Timeout- und Netzwerkfehler: Retry
• typische permanente 4xx: direkt nach failed
• nach MaxRetries: nach failed

Microsoft 365 / Security

Der Relay verwendet:

Microsoft Graph
Application Mail.Send

über Exchange Online Application RBAC.

Die Berechtigung wird auf das beim Setup angegebene Absenderpostfach beschränkt.

Beispiel:

SMTPGraphRelay App
        |
        | Application Mail.Send
        v
info@example.com

Die App erhält bewusst keine zusätzliche tenantweite Graph Mail.Send Application Permission, da diese das Exchange-RBAC-Scoping umgehen würde.

Der lokale Relay erzwingt außerdem standardmäßig:

"ForceSender": true

und verwendet ausschließlich Graph.SenderMailbox als Graph-Absender.

Zertifikatsauthentifizierung

SMTPGraphRelay verwendet kein Client Secret.

Das Setup erzeugt ein RSA-Zertifikat unter:

Cert:\LocalMachine\My

Der private Schlüssel ist nicht exportierbar.

Das Relay prüft regelmäßig die Restlaufzeit des Zertifikats.

Standard:

Warnung:   60 Tage
Kritisch:  14 Tage
Prüfung:   alle 12 Stunden

Zur Rotation:

.\Renew-SMTPGraphRelayCertificate.ps1

Die Rotation erfolgt mit Überlappung:

OLD
 ↓
NEW erzeugen
 ↓
OLD + NEW in Entra
 ↓
NEW testen
 ↓
Config auf NEW
 ↓
Relay neu starten
 ↓
OLD optional entfernen

Log-Rotation

Standard:

MaxFileSizeMB = 10
RetentionDays = 30
CleanupHours  = 12

Aktives Log:

logs\SMTPGraphRelay.log

Archiv:

logs\SMTPGraphRelay-YYYYMMDD-HHMMSS.log

Health Check

.\Test-SMTPGraphRelay.ps1

Optional mit echter SMTP-Testmail:

.\Test-SMTPGraphRelay.ps1 `
    -SendTestMail `
    -TestRecipient "user@example.com"

Der Health Check prüft unter anderem:

• PowerShell-Version
• Administratorstatus
• Config
• Graph-Modul
• Zertifikat und Private Key
• Zertifikatslaufzeit
• Queue und Schreibrechte
• Failed Queue
• Scheduled Task
• SMTP Listener
• Graph App-only Authentication

Exitcodes:

0 = OK
1 = Warnung
2 = Fehler

Online Update

Im Manager:

[3] Nach Online-Updates suchen

Der Manager prüft:

https://me-gitea.maieredv.cloud/MAIEREDV/SMTPGraphRelay/raw/branch/main/version.json

und lädt bei Bedarf:

https://me-gitea.maieredv.cloud/MAIEREDV/SMTPGraphRelay/archive/main.zip

Vor dem Update wird ein Backup der verwalteten Programmdateien erstellt.

Bei einem fehlgeschlagenen Health Check erfolgt automatisch ein Rollback.

Von Updates niemals überschrieben

• config.json
• queue\
• failed\
• logs\
• backup\
• lokales Zertifikat
• Entra App Registration
• Exchange Application RBAC

Repair

[2] Installation aus Gitea reparieren

Repair lädt den aktuellen Programmstand neu aus dem Repository und repariert:

• Programmdateien
• PowerShell-Module
• Verzeichnisstruktur
• Firewallregel
• Scheduled Task

Cloud-Konfiguration, Zertifikat, Config, Queue und Logs bleiben erhalten.

Repository

https://me-gitea.maieredv.cloud/MAIEREDV/SMTPGraphRelay

Systemvoraussetzungen

• Windows 10 / 11 oder Windows Server
• Windows PowerShell 5.1
• lokale Administratorrechte für Installation
• Internetzugang zu Microsoft Entra, Microsoft Graph, Exchange Online und dem Gitea-Repository
• Entra-/Exchange-Administratorkonto für die Ersteinrichtung
• Microsoft-365-/Exchange-Online-Postfach für den Relay-Absender