325 lines
6.7 KiB
Markdown
325 lines
6.7 KiB
Markdown
# 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:
|
|
|
|
```powershell
|
|
$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:
|
|
|
|
```text
|
|
C:\Program Files\SMTPGraphRelay
|
|
```
|
|
|
|
Es muss kein ZIP manuell heruntergeladen oder entpackt werden.
|
|
|
|
## Installer / Manager
|
|
|
|
```text
|
|
[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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
Microsoft Graph
|
|
Application Mail.Send
|
|
```
|
|
|
|
über **Exchange Online Application RBAC**.
|
|
|
|
Die Berechtigung wird auf das beim Setup angegebene Absenderpostfach beschränkt.
|
|
|
|
Beispiel:
|
|
|
|
```text
|
|
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:
|
|
|
|
```json
|
|
"ForceSender": true
|
|
```
|
|
|
|
und verwendet ausschließlich `Graph.SenderMailbox` als Graph-Absender.
|
|
|
|
## Zertifikatsauthentifizierung
|
|
|
|
SMTPGraphRelay verwendet kein Client Secret.
|
|
|
|
Das Setup erzeugt ein RSA-Zertifikat unter:
|
|
|
|
```text
|
|
Cert:\LocalMachine\My
|
|
```
|
|
|
|
Der private Schlüssel ist nicht exportierbar.
|
|
|
|
Das Relay prüft regelmäßig die Restlaufzeit des Zertifikats.
|
|
|
|
Standard:
|
|
|
|
```text
|
|
Warnung: 60 Tage
|
|
Kritisch: 14 Tage
|
|
Prüfung: alle 12 Stunden
|
|
```
|
|
|
|
Zur Rotation:
|
|
|
|
```powershell
|
|
.\Renew-SMTPGraphRelayCertificate.ps1
|
|
```
|
|
|
|
Die Rotation erfolgt mit Überlappung:
|
|
|
|
```text
|
|
OLD
|
|
↓
|
|
NEW erzeugen
|
|
↓
|
|
OLD + NEW in Entra
|
|
↓
|
|
NEW testen
|
|
↓
|
|
Config auf NEW
|
|
↓
|
|
Relay neu starten
|
|
↓
|
|
OLD optional entfernen
|
|
```
|
|
|
|
## Log-Rotation
|
|
|
|
Standard:
|
|
|
|
```text
|
|
MaxFileSizeMB = 10
|
|
RetentionDays = 30
|
|
CleanupHours = 12
|
|
```
|
|
|
|
Aktives Log:
|
|
|
|
```text
|
|
logs\SMTPGraphRelay.log
|
|
```
|
|
|
|
Archiv:
|
|
|
|
```text
|
|
logs\SMTPGraphRelay-YYYYMMDD-HHMMSS.log
|
|
```
|
|
|
|
## Health Check
|
|
|
|
```powershell
|
|
.\Test-SMTPGraphRelay.ps1
|
|
```
|
|
|
|
Optional mit echter SMTP-Testmail:
|
|
|
|
```powershell
|
|
.\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:
|
|
|
|
```text
|
|
0 = OK
|
|
1 = Warnung
|
|
2 = Fehler
|
|
```
|
|
|
|
## Online Update
|
|
|
|
Im Manager:
|
|
|
|
```text
|
|
[3] Nach Online-Updates suchen
|
|
```
|
|
|
|
Der Manager prüft:
|
|
|
|
```text
|
|
https://me-gitea.maieredv.cloud/MAIEREDV/SMTPGraphRelay/raw/branch/main/version.json
|
|
```
|
|
|
|
und lädt bei Bedarf:
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
[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
|
|
|
|
```text
|
|
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
|