207 lines
7.2 KiB
Markdown
207 lines
7.2 KiB
Markdown
# CardSync 🔄
|
|
|
|
**Synology CardDAV → Microsoft 365 Kontakte** — Self-hosted, Docker-basiert.
|
|
|
|
Synchronisiert Kontakte von einem Synology CardDAV-Server automatisch in die Microsoft 365 Kontakte deiner Benutzer. Benutzer melden sich einmalig per Microsoft OAuth an, ein Admin konfiguriert den Synology-Server zentral.
|
|
|
|
---
|
|
|
|
## Voraussetzungen
|
|
|
|
- Docker & Docker Compose
|
|
- Synology NAS mit aktiviertem CardDAV-Server (Paket: „CardDAV Server" oder „Contacts")
|
|
- Microsoft Azure App-Registrierung
|
|
|
|
---
|
|
|
|
## Schnellstart
|
|
|
|
### Azure App-Registrierung erstellen
|
|
|
|
CardSync unterstützt zwei Betriebsmodi — du kannst sie **kombinieren oder nur einen** nutzen:
|
|
|
|
**Modus A: OAuth-Login (Delegated Permissions)**
|
|
User melden sich einmalig per Microsoft-Login an. Empfohlen für kleine Setups oder zum Testen.
|
|
|
|
**Modus B: Azure AD Gruppen-Import (Application Permissions) — empfohlen für Firmen**
|
|
Admin trägt eine Azure AD Gruppen-ID ein, alle Mitglieder werden automatisch importiert. Kein User-Login nötig.
|
|
|
|
#### Setup-Schritte:
|
|
|
|
1. Gehe zu [portal.azure.com](https://portal.azure.com) → **Azure Active Directory** → **App-Registrierungen**
|
|
2. **Neue Registrierung** → Name: `CardSync`
|
|
3. Kontotypen: nur eigene Organisation
|
|
4. Redirect-URI (Web): `https://deine-ip-oder-domain/auth/callback`
|
|
5. Unter **Zertifikate & Geheimnisse** ein neues Client-Secret erstellen → notieren
|
|
|
|
**Berechtigungen** unter **API-Berechtigungen** → **Microsoft Graph**:
|
|
|
|
*Für Modus A (Delegated):*
|
|
- `Contacts.ReadWrite` (Delegiert)
|
|
- `offline_access`, `openid`, `profile`, `email`
|
|
|
|
*Für Modus B (Application — Goldstandard):*
|
|
- `Contacts.ReadWrite` (**Anwendung** — wichtig, nicht delegiert!)
|
|
- `User.Read.All` (Anwendung)
|
|
- `GroupMember.Read.All` (Anwendung)
|
|
- Danach **„Administratorzustimmung erteilen"** klicken
|
|
|
|
Beide Modi können parallel laufen — User können sich entweder selbst anmelden (Modus A), oder werden per Gruppen-Import angelegt (Modus B).
|
|
|
|
### 2. Repository vorbereiten
|
|
|
|
```bash
|
|
git clone <dieses-repo>
|
|
cd cardsync
|
|
cp .env.example .env
|
|
```
|
|
|
|
### 3. `.env` konfigurieren
|
|
|
|
```env
|
|
# Datenbank
|
|
POSTGRES_PASSWORD=sicher_aendern_123
|
|
|
|
# Sicherheit (langen zufälligen String generieren: openssl rand -hex 32)
|
|
SECRET_KEY=dein_langer_zufaelliger_key
|
|
|
|
# Microsoft Azure
|
|
MS_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
|
MS_CLIENT_SECRET=dein-client-secret
|
|
MS_TENANT_ID=common # oder deine Tenant-ID für Single-Tenant
|
|
|
|
# URL unter der die App erreichbar ist (KEIN trailing slash)
|
|
APP_BASE_URL=http://192.168.1.100
|
|
|
|
# Admin-E-Mails (kommagetrennt) — diese Benutzer bekommen Admin-Zugang
|
|
ADMIN_EMAILS=admin@firma.de,it@firma.de
|
|
```
|
|
|
|
### 4. Starten
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
Die App ist jetzt unter `https://localhost` erreichbar (HTTP wird automatisch auf HTTPS umgeleitet).
|
|
|
|
> ⚠️ **Beim ersten Start** wird automatisch ein selbstsigniertes Zertifikat erzeugt — der Browser zeigt eine Sicherheitswarnung. Einmal akzeptieren und weitermachen.
|
|
|
|
### 5. (Optional) Eigenes Zertifikat hinterlegen
|
|
|
|
Wenn du ein Wildcard- oder CA-signiertes Zertifikat hast:
|
|
|
|
```bash
|
|
# Lege deine Dateien EXAKT mit diesen Namen ab:
|
|
cp dein-wildcard.crt ./nginx/certs/cert.pem
|
|
cp dein-wildcard.key ./nginx/certs/key.pem
|
|
|
|
# Frontend neu starten — das war's
|
|
docker compose restart frontend
|
|
```
|
|
|
|
Details und PFX-Konvertierung: siehe `nginx/certs/README.md`
|
|
|
|
---
|
|
|
|
## Verwendung
|
|
|
|
### Admin-Einrichtung
|
|
|
|
1. Gehe zu `http://deine-ip/auth/login?mode=admin`
|
|
2. Melde dich mit einem der Admin-Microsoft-Accounts an
|
|
3. Gehe im Admin-Dashboard zu **Synology Config**
|
|
4. Trage Server-URL, Benutzername und Passwort ein
|
|
5. Teste die Verbindung mit **Verbindung testen**
|
|
|
|
### Benutzer-Onboarding (Modus A — OAuth)
|
|
|
|
1. Benutzer rufen `http://deine-ip` auf
|
|
2. Klick auf **Mit Microsoft anmelden**
|
|
3. Microsoft OAuth-Zustimmung (Kontakte-Zugriff)
|
|
4. Adressbuch auswählen und Sync-Intervall einstellen
|
|
5. Optional: **Jetzt synchronisieren** für den ersten sofortigen Sync
|
|
|
|
### Benutzer-Import via Azure AD Gruppe (Modus B — empfohlen für Firmen)
|
|
|
|
1. Admin-Dashboard → **Azure AD Gruppe**
|
|
2. Object-ID der Azure AD Gruppe eintragen (aus Azure Portal → AD → Gruppen → deine Gruppe → Object ID)
|
|
3. Default-Adressbuch und Default-Sync-Intervall für neue User wählen
|
|
4. **Gruppe testen** klicken → sollte die Mitgliederzahl anzeigen
|
|
5. **Speichern**, dann **Mitglieder jetzt importieren**
|
|
6. Alle Gruppenmitglieder sind nun in CardSync angelegt, Sync läuft automatisch
|
|
7. Mitgliedschaft wird im konfigurierten Intervall (Default: 6h) automatisch aktualisiert
|
|
|
|
### Admin: Benutzer verwalten
|
|
|
|
- Im Admin-Dashboard unter **Benutzer** alle angemeldeten Benutzer sehen
|
|
- Pro Benutzer: Adressbuch zuweisen, Intervall konfigurieren, Sync aktivieren/deaktivieren
|
|
- Manuellen Sync für jeden Benutzer triggern
|
|
- Sync-Logs einsehen
|
|
|
|
---
|
|
|
|
## Synology CardDAV-Server einrichten
|
|
|
|
1. Im Synology Package Center „**CardDAV Server**" installieren
|
|
2. Oder im Paket „**Contacts**": CardDAV ist automatisch aktiv
|
|
3. Standard-Port: **5006** (HTTP) oder **5007** (HTTPS)
|
|
4. Server-URL-Format: `http://192.168.1.10:5006` oder `https://nas.firma.de:5007`
|
|
|
|
---
|
|
|
|
## Architektur
|
|
|
|
```
|
|
┌─────────────────────────────────────────────┐
|
|
│ Docker Compose │
|
|
│ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Nginx │──▶│ FastAPI │──▶│PostgreSQL│ │
|
|
│ │ :80 │ │ :8000 │ │ :5432 │ │
|
|
│ └──────────┘ └────┬─────┘ └──────────┘ │
|
|
└───────────────────────┼─────────────────────┘
|
|
│
|
|
┌────────────┴────────────┐
|
|
│ │
|
|
┌──────▼──────┐ ┌────────▼──────┐
|
|
│ Synology │ │ Microsoft │
|
|
│ CardDAV │ │ Graph API │
|
|
│ (CardDAV │ │ (REST/OAuth) │
|
|
│ Protokoll)│ └───────────────┘
|
|
└─────────────┘
|
|
```
|
|
|
|
**Sync-Richtung:** Nur Synology → MS365 (einseitig)
|
|
|
|
**Matching-Strategie:**
|
|
- Kontakte werden per UID (vCard UID-Feld) gematcht
|
|
- Die UID wird beim ersten Sync in den MS365-Notizen hinterlegt
|
|
- Gelöschte Synology-Kontakte werden aus MS365 entfernt
|
|
|
|
---
|
|
|
|
## Sicherheitshinweise
|
|
|
|
- In Produktion: HTTPS-Reverse-Proxy (z.B. Traefik, Caddy, nginx mit Let's Encrypt) vorschalten
|
|
- `SECRET_KEY` und `POSTGRES_PASSWORD` immer ändern
|
|
- Das Synology-Passwort wird aktuell im Klartext in der DB gespeichert (für Produktion: Verschlüsselung ergänzen)
|
|
- Microsoft Tokens werden per JWT-Session verwaltet und automatisch refresht
|
|
|
|
---
|
|
|
|
## Logs
|
|
|
|
```bash
|
|
docker compose logs -f backend # Backend-Logs mit Sync-Aktivitäten
|
|
docker compose logs -f frontend # Nginx-Logs
|
|
```
|
|
|
|
---
|
|
|
|
## Entwicklung / Updates
|
|
|
|
```bash
|
|
docker compose down
|
|
docker compose up -d --build
|
|
```
|