Kapitel 11 Clients, Groupware & CLI Admin: #pApiAuth

Scoped API-Keys, sharpmail-cli (Infrastructure-as-Code), SCIM 2.0, OIDC & Pflicht-Signaturen

Automatisierungs-Pipelines (Ansible, Terraform, GitLab CI), Shops, Ticketsysteme und ERP-Lösungen sollten niemals das persönliche Passwort eines Mitarbeiters mitbenutzen. Unter API-Keys, SSO & Regeln (#pApiAuth) erstellst du rollenbasierte Scoped API-Schlüssel, steuerst den Server deklarativ über die integrierte sharpmail-cli und verwaltest zentrale Pflicht-Fußzeilen.

Praxis-Tipp & Architektur-Hinweis

Keine separate CLI-Binary nötig: sharpmail-cli ist direkt in SharpMailserver.Server integriert (auf Linux/macOS/Docker automatisch als /usr/local/bin/sharpmail-cli verlinkt, unter Windows als SharpMailserver.Server.exe cli). Konten mit aktivierter 2FA blockieren einfache HTTP-Basic-Passwort-Logins automatisch - verwende für Automatisierung immer einen Scoped API-Key (SHARPMAIL_TOKEN=smk_...).

Praxis-Beispiele für sharpmail-cli & Infrastructure-as-Code

Setze SHARPMAIL_URL und SHARPMAIL_TOKEN als Umgebungsvariablen, damit kein Geheimnis in der Prozessliste auftaucht.

Referenz / Konfiguration

export SHARPMAIL_URL="https://mail.firma.de"
export SHARPMAIL_TOKEN="smk_01968f2a_..."

# Schema & Felder eines Objekttyps anzeigen
sharpmail-cli describe Account

# Alle Postfächer als NDJSON für jq abfragen
sharpmail-cli query Account --json | jq -r '.email'

# Kompletten Ist-Zustand exportieren & Änderungen per Dry-Run prüfen
sharpmail-cli snapshot > prod-state.ndjson
sharpmail-cli apply --file prod-state.ndjson --dry-run

Einstellungen, Standardwerte & Best Practices

Einstellung / Ort	Funktion	Standardwert	Best Practice im Betrieb
`Scoped API-Keys (smk_<id>_<secret>)`	Rollenbasierte Bearer- / X-Api-Key-Schlüssel mit Argon2id/SHA-256-Speicherung, RBAC-Scope (User, ComplianceAuditor, TenantAdmin, ServerAdmin), Standard-E-Mail-Kategorie, CIDR-IP-Allowlist und optionalem Ablaufdatum.	`Role = User (Least Privilege)`	Für Shops/ERP Role = User (nur /api/v1/send) mit passender Standard-Kategorie (z. B. critical für Login/2FA, transactional für Rechnungen) wählen; für CI/CD Role = TenantAdmin oder ServerAdmin mit CIDR und 90 Tagen Laufzeit vergeben.
`IP-Warming, Kategorien & Empfänger-Anbieter-Limits (/api/v1/send)`	Steuert separate Stunden- und Tages-Kontingente pro E-Mail-Kategorie (critical, transactional, notification, marketing) klar getrennt nach Empfänger-Anbieter (Google/Gmail, Microsoft Outlook/Hotmail/Live, Yahoo & AOL, T-Online/GMX/WEB.DE, Apple iCloud) sowie isoliert je einzelner Ziel-Domain (*).	`28-Tage IP-Warming / 100 % Produktion`	Bei neuen Server-IPs das 28-Tage-IP-Warming aktivieren (5 % -> 100 %): Kritische 2FA-Mails umgehen das Warming sofort (BypassWarming + Priorität 10), während Benachrichtigungen und Marketing-Mails sanft über künftige Stundenfenster gepaced werden (DeferQueue) oder per HTTP 429 + Retry-After rückmelden.
`sharpmail-cli (describe / get / query / create / update / delete / dns)`	Schema-getriebene Kommandozeile mit lokalem XDG-/AppData-Schema-Cache, Tabellen-Ausgabe sowie einzeiligem JSON und NDJSON-Streams (--json) für jq.	`SHARPMAIL_URL + SHARPMAIL_TOKEN`	Mit sharpmail-cli describe <Typ> verfügbare Felder prüfen; mit sharpmail-cli query Account --json \| jq Bestände skripten und mit sharpmail-cli dns firma.de --bind fertige BIND-Zonen exportieren.
`Deklaratives IaC (sharpmail-cli snapshot & apply --dry-run)`	Exportiert Tenants, Domains (inkl. Dual-DKIM-Modus), Postfächer, Verteiler, Aliase und Server-Policies als idempotenten NDJSON-Plan und spielt Änderungen per apply wieder ein.	`--dry-run vor jedem Rollout`	Konfiguration per sharpmail-cli snapshot in Git versionieren und Änderungen in Staging/Produktion zuerst mit sharpmail-cli apply --file plan.ndjson --dry-run prüfen.
`Globale Pflicht-Signatur / Disclaimer`	Fügt ausgehenden E-Mails automatisch das gesetzliche Unternehmens-Impressum (HGB / GmbHG) vor der DKIM-Signatur im HTML- und Text-Teil an (inkl. Duplikatschutz).	`Optional aktivierbar`	Sowohl HTML- als auch Reintext-Variante hinterlegen und den Duplikatschutz aktiviert lassen, damit Antwortketten sauber bleiben.
`OIDC Single Sign-On & SCIM 2.0`	Bindet Microsoft Entra ID, Keycloak, Authentik oder Okta für passwortloses Webmail-SSO sowie automatische Benutzer-Provisionierung (/scim/v2) an.	`Lokale Auth + Passkeys aktiv`	Für maximale Sicherheit WebAuthn Passkeys (FIDO2) aktivieren; für SCIM 2.0 einen Scoped API-Key mit Rolle TenantAdmin und CIDR-Filter des IdP nutzen.