docs: CalDAV-Konfiguration und CALDAV_ALLOWED_CIDRS in deployment.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-24 13:04:20 +02:00
parent 7e19311d2a
commit a639de13f8
1 changed files with 75 additions and 0 deletions
@@ -426,4 +426,79 @@ Update-Reihenfolge:
 2. Migration zuerst auf 137, dann auf 164
 3. Service-Restart auf 137, dann auf 164

+---
+
+## CalDAV-Konfiguration
+
+TimeMaster ist ein **reiner CalDAV-Client** – es stellt keinen eigenen CalDAV-Server bereit. Genehmigte Abwesenheiten werden als iCal-Events per HTTP PUT in einen externen Kalenderserver (typischerweise Nextcloud) geschrieben.
+
+### Funktionsweise
+
+```
+TimeMaster ──PUT/DELETE──► Nextcloud CalDAV
+            ◄─────────────  (kein eingehender Traffic von Nextcloud)
+```
+
+- Kein Kalender-Client (Thunderbird, Apple Calendar etc.) kann sich mit TimeMaster verbinden.
+- TimeMaster kann nicht als CalDAV-Relay oder -Proxy konfiguriert werden.
+
+### SSRF-Schutz
+
+Alle CalDAV-URLs werden vor jedem HTTP-Request auf SSRF-Risiken geprüft. Standardmäßig sind folgende Adressbereiche gesperrt:
+
+| Bereich | Grund |
+|---------|-------|
+| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC 1918 (private Netze) |
+| `127.0.0.0/8` | Loopback |
+| `169.254.0.0/16` | Link-local / Cloud-Metadaten (AWS, GCP, Azure) |
+| `::1/128`, `fc00::/7`, `fe80::/10` | IPv6 intern |
+
+### Interne Nextcloud freischalten (CALDAV_ALLOWED_CIDRS)
+
+Wenn die Nextcloud-Instanz **im internen Netz** betrieben wird (häufig bei On-Premises-Deployments), muss das entsprechende Netz explizit per `.env`-Variable freigeschaltet werden:
+
+**Schritt 1 – `.env` auf dem Server bearbeiten:**
+
+```bash
+ssh root@192.168.1.137 "nano /opt/timemaster/backend/.env"
+```
+
+**Schritt 2 – Variable hinzufügen oder ergänzen:**
+
+```bash
+# Einzelner Host (empfohlen wenn möglich):
+CALDAV_ALLOWED_CIDRS=192.168.1.50/32
+
+# Ganzes Subnetz:
+CALDAV_ALLOWED_CIDRS=192.168.1.0/24
+
+# Mehrere Einträge kommasepariert:
+CALDAV_ALLOWED_CIDRS=192.168.1.0/24,10.10.5.0/28
+
+# Nextcloud auf Port 8080, nur dieser Host:
+CALDAV_ALLOWED_CIDRS=10.0.1.20/32
+```
+
+**Schritt 3 – Service neu starten:**
+
+```bash
+ssh root@192.168.1.137 "systemctl restart timemaster"
+```
+
+**Schritt 4 – Verbindung testen** (in der TimeMaster-Oberfläche unter Einstellungen → CalDAV → „Verbindung testen").
+
+> **Sicherheitshinweis:** So eng wie möglich einschränken – lieber `/32` (einzelner Host) als `/24` (ganzes Subnetz). Der Rest des internen Netzes bleibt weiterhin gesperrt.
+
+### Nextcloud-Kalender-URL ermitteln
+
+In Nextcloud die Kalender-URL findet man unter:
+**Kalender-App → Kalender-Einstellungen (Zahnrad) → Primäre CalDAV-Adresse kopieren**
+
+Typisches Format:
+```
+https://nextcloud.example.com/remote.php/dav/calendars/USERNAME/KALENDER-NAME/
+```
+
+Für den Firmenkalender empfiehlt sich ein dedizierter Nextcloud-User (z.B. `timemaster-sync`), damit keine persönlichen Zugangsdaten hinterlegt werden müssen.
+
 Bei divergentem Datenbankzustand zwischen den Servern: Server 164 aus dem Dump von Server 137 wiederherstellen.