beauty-bookings/docs/caldav-setup.md

CalDAV-Kalender Einrichtung

Übersicht

Die App bietet einen CalDAV-Endpunkt, um Buchungen in externe Kalender-Apps zu synchronisieren. Aus Sicherheitsgründen erfolgt die Authentifizierung per Header. Unterstützt werden:

• Authorization: Bearer
• Basic Auth, wobei der Token als Benutzername übergeben wird (Passwort leer/optional)

Token generieren

1. Als Admin einloggen
2. Im Admin-Bereich den CalDAV-Token generieren
3. Token und URL werden angezeigt

Wichtig: Der Token ist 24 Stunden gültig. Danach muss ein neuer Token generiert werden.

Endpunkt

GET /caldav/calendar/events.ics
Authorization: Bearer <TOKEN>

oder

Authorization: Basic <base64(token:)>   # Token als Benutzername, Passwort leer

Unterstützte Kalender-Apps

✅ Thunderbird (empfohlen)

1. Kalender → Neuer Kalender → Im Netzwerk
2. Format: CalDAV
3. Standort: CalDAV-URL eingeben
4. Benutzername: Den generierten Token eingeben (Basic Auth)
5. Passwort: Leer lassen

✅ Outlook (mit Einschränkungen)

1. Datei → Kontoeinstellungen → Internetkalender
2. URL eingeben
3. Erweiterte Einstellungen → Benutzerdefinierte Header:

   Authorization: Bearer <TOKEN>
   

Hinweis: Nicht alle Outlook-Versionen unterstützen benutzerdefinierte Header.

⚠️ Apple Calendar (eingeschränkt)

Apple Calendar unterstützt keine Authorization-Header für Kalenderabonnements.

Alternativen:

• Manuelle ICS-Datei importieren (nicht automatisch aktualisiert)
• CalDAV-Bridge verwenden (z.B. über Proxy)

⚠️ Google Calendar (eingeschränkt)

Google Calendar unterstützt keine Authorization-Header für URL-Abonnements.

Alternativen:

• Google Apps Script als Bridge verwenden
• Manuelle ICS-Datei importieren

Testen mit cURL

# Bearer
curl -H "Authorization: Bearer <DEIN_TOKEN>" \
  https://deine-domain.de/caldav/calendar/events.ics

# Basic (Token als Benutzername, Passwort leer)
curl -H "Authorization: Basic $(printf "%s" "<DEIN_TOKEN>:" | base64)" \
  https://deine-domain.de/caldav/calendar/events.ics

Erwartete Antwort: ICS-Datei mit allen bestätigten und ausstehenden Buchungen.

Sicherheit

Warum Authorization-Header?

• Query-Parameter (?token=...) werden in Browser-History, Server-Logs und Referrer-Headers gespeichert
• Authorization-Header werden nicht geloggt und nicht in der URL sichtbar
• Folgt REST-API Best Practices

Token-Verwaltung

• Token sind 24 Stunden gültig
• Abgelaufene Token werden automatisch beim nächsten Zugriff gelöscht
• Bei Bedarf neuen Token generieren (alte Token werden nicht automatisch invalidiert)

Backward Compatibility

Die alte Methode mit Query-Parameter (?token=...) wird noch unterstützt, aber als deprecated markiert. Der Server sendet zusätzlich Response-Header (Deprecation: true und Warning: 299 ...). Eine Warnung wird im Server-Log ausgegeben.

Troubleshooting

"Unauthorized - Token required"

• Prüfe, ob der Authorization-Header korrekt gesetzt ist
• Format: Authorization: Bearer <TOKEN> (mit Leerzeichen nach "Bearer")

"Unauthorized - Invalid or expired token"

• Token ist abgelaufen (24h Gültigkeit)
• Generiere einen neuen Token im Admin-Bereich

Kalender zeigt keine Termine

• Prüfe, ob Buchungen mit Status "confirmed" oder "pending" existieren
• Teste den Endpunkt mit cURL
• Prüfe Server-Logs auf Fehler

Zukünftige Verbesserungen

• Langlebige Token mit Refresh-Mechanismus
• Token-Revocation-Endpoint
• CalDAV-Bridge für Apple Calendar und Google Calendar
• Webhook-basierte Push-Notifications statt Polling