archivmail/features/PROJ-16-ldap-active-directory.md

id, title, status, priority, created

id	title	status	priority	created
PROJ-16	LDAP / Active Directory Anbindung	In Progress	P1	2026-03-13

PROJ-16 — LDAP / Active Directory Anbindung

Ziel

Authentifizierung gegen einen LDAP-Server (OpenLDAP, Microsoft Active Directory, Samba AD). Lokale Accounts bleiben weiterhin nutzbar. LDAP-User werden beim ersten Login automatisch in der Datenbank angelegt (source: ldap) und bei jedem Login synchronisiert.

User Stories

• Als Admin möchte ich LDAP in config.yml konfigurieren, damit Mitarbeiter ihre bestehenden Windows/AD-Zugangsdaten nutzen können.
• Als Endnutzer möchte ich mich mit meinem AD-Passwort anmelden, ohne einen separaten archivmail-Account zu benötigen.
• Als Admin möchte ich LDAP-User einer Rolle (user/auditor/admin) zuweisen können, entweder per fester Zuordnung oder über AD-Gruppen.
• Als Admin möchte ich LDAP deaktivieren können, ohne den restlichen Betrieb zu stören.

Akzeptanzkriterien

• Login mit LDAP-Credentials funktioniert wenn ldap.enabled: true
• Lokale Accounts funktionieren weiterhin (Fallback wenn LDAP fehlschlägt oder deaktiviert)
• LDAP-User werden beim Login automatisch via UpsertLDAPUser angelegt/aktualisiert
• Rollen-Mapping via AD-Gruppen konfigurierbar (optional, Fallback: default_role)
• STARTTLS und LDAPS (Port 636) werden unterstützt
• Bind-User (Service Account) für AD-Suche konfigurierbar
• Fehlermeldung bei falschem Passwort ist identisch zu lokalem Login (kein Info-Leak)
• LDAP-Fehler landen im Audit-Log
• Konfigurierbar per config.yml Abschnitt ldap:

Konfigurationsformat (config.yml)

ldap:
  enabled: true
  url: "ldap://192.168.1.10:389"          # oder ldaps://...
  bind_dn: "CN=archivmail-svc,OU=ServiceAccounts,DC=corp,DC=local"
  bind_password: "geheim"
  base_dn: "OU=Users,DC=corp,DC=local"
  user_filter: "(sAMAccountName=%s)"       # %s wird durch eingegebenen Username ersetzt
  tls: false                               # STARTTLS
  tls_skip_verify: false
  default_role: "user"                     # Rolle für neue LDAP-User
  group_mappings:                          # optional: AD-Gruppe → archivmail-Rolle
    - group_dn: "CN=archivmail-admins,OU=Groups,DC=corp,DC=local"
      role: "admin"
    - group_dn: "CN=archivmail-auditors,OU=Groups,DC=corp,DC=local"
      role: "auditor"

Technische Umsetzung

Neues Paket: internal/ldapauth

internal/ldapauth/
  ldap.go          — Client, Bind, Search, Authenticate
  ldap_test.go     — Tests mit Mock-LDAP

Abhängigkeit: github.com/go-ldap/ldap/v3

Ablauf Login mit LDAP

1. auth.Manager.Login(username, password) prüft zuerst lokale DB
2. Wenn lokaler User nicht gefunden UND LDAP aktiviert → LDAP-Auth versuchen
3. LDAP-Bind mit Service Account → User-DN per user_filter suchen
4. User-Bind mit gefundener DN + eingegebenem Passwort
5. Optional: Gruppen-Mitgliedschaft abfragen → Rolle bestimmen
6. userstore.UpsertLDAPUser(username, email, role) aufrufen
7. JWT-Token wie bei lokalem Login ausstellen

Felder aus LDAP lesen

LDAP-Attribut	archivmail-Feld
sAMAccountName / uid	username
mail	email
memberOf	→ Gruppen-Mapping → role
displayName	(für spätere Anzeige)

API-Endpunkt: GET /api/admin/ldap/test (admin only)

Testet die LDAP-Verbindung und gibt Status zurück:

{"ok": true, "message": "LDAP-Verbindung erfolgreich", "users_found": 42}

Nicht in diesem Feature

• Automatische User-Synchronisation (Bulk-Import aller AD-User) — separates Feature
• LDAP-Gruppen als Postfach-Zuweisungen
• Kerberos / SAML / OAuth2 (separate Features)

Dateien

• internal/ldapauth/ldap.go (neu)
• internal/auth/auth.go (erweitert: LDAP-Fallback)
• config/config.go (erweitert: LDAPConfig)
• cmd/archivmail/main.go (erweitert: LDAP-Client initialisieren)
• internal/api/server.go (erweitert: /api/admin/ldap/test)
• install.sh (erweitert: LDAP-Kommentar in config.yml)