Mailcow mit authentik – Single Sign-On für deinen Mailserver

Serie: Mailcow Dockerized + authentik
Teil 1 von 2
In diesem ersten Teil richten wir authentik so ein, dass Mailcow später als OpenID-Connect-Anwendung (OIDC) angebunden werden kann.

Einleitung

Wer mehrere Self-Hosted-Dienste betreibt, kennt das Problem: Jeder Dienst besitzt seine eigene Benutzerverwaltung, eigene Passwörter und eigene Sicherheitsrichtlinien.

Mit authentik lässt sich dieses Problem elegant lösen. Als zentrale Identity- und Access-Management-Lösung übernimmt authentik die Authentifizierung für nahezu alle bekannten Self-Hosted-Anwendungen. Benutzer melden sich nur noch einmal an und können anschließend mit Single Sign-On auf alle freigegebenen Dienste zugreifen.

Seit Mailcow 2025 unterstützt auch Mailcow Dockerized die Anmeldung über Generic OpenID Connect (OIDC). Dadurch kann authentik als zentraler Identity Provider eingesetzt werden. Benutzer melden sich anschließend ausschließlich über authentik an, während Mailcow die eigentliche Mailbox verwaltet.

Das bringt zahlreiche Vorteile:

Single Sign-On (SSO)
Zentrale Benutzerverwaltung
Multi-Faktor-Authentifizierung nur an einer Stelle
Passwortrichtlinien zentral verwalten
WebAuthn/FIDO2-Unterstützung
Benutzer können automatisch in Mailcow angelegt werden
App-Passwörter für Thunderbird, Outlook und Smartphones bleiben weiterhin möglich

In diesem Artikel richten wir die komplette Integration Schritt für Schritt ein.

Ziel der Konfiguration

Nach Abschluss dieser Anleitung läuft die Anmeldung folgendermaßen ab:

Benutzer
      │
      ▼
Mailcow Login
      │
      ▼
Weiterleitung zu authentik
      │
      ▼
Benutzer meldet sich an
      │
      ▼
OIDC Token
      │
      ▼
Mailcow
      │
      ▼
Mailbox wird geöffnet

Voraussetzungen

Bevor wir beginnen, sollte Folgendes bereits vorhanden sein.

Mailcow Dockerized

Eine funktionierende Mailcow-Installation.

Beispielsweise erreichbar unter

https://mail.example.com

authentik

Eine funktionierende authentik-Installation.

Beispielsweise

https://auth.example.com

HTTPS

Beide Systeme müssen über gültige TLS-Zertifikate erreichbar sein.

OIDC funktioniert ausschließlich über HTTPS.

DNS

Die verwendeten Domains müssen korrekt aufgelöst werden.

Beispielsweise:

mail.example.com
auth.example.com

Wie funktioniert die Anmeldung?

Bevor wir mit der Konfiguration beginnen, lohnt sich ein kurzer Blick auf den Ablauf.

Mailcow speichert weiterhin:

Mailboxen
Mailquoten
Aliase
Domains
Berechtigungen

authentik übernimmt dagegen ausschließlich:

Anmeldung
MFA
Passwort
Benutzeridentität
Tokens

Mailcow fragt beim Login lediglich authentik:

„Ist dieser Benutzer erfolgreich angemeldet?“

authentik beantwortet diese Anfrage mit einem signierten OIDC-Token.

Mailcow prüft dieses Token und meldet den Benutzer anschließend an.

Das Passwort kennt Mailcow dabei gar nicht.

Vorbereitung

Die offizielle Integrationsanleitung verwendet zwei Platzhalter:

Platzhalter	Bedeutung
`mailcow.company`	FQDN deiner Mailcow-Installation
`authentik.company`	FQDN deiner authentik-Instanz

In unserem Beispiel verwenden wir:

Mailcow:
mail.example.com

authentik:
auth.example.com

Passe sämtliche URLs später entsprechend deiner Umgebung an.

Besonderheiten der aktuellen authentik-Versionen

Seit authentik 2026.5 wurde das Handling der Redirect-URIs angepasst.

Bei neuen Installationen muss die Redirect URI explizit als

Strict → Authorization

angelegt werden.

Ältere Versionen behandeln Redirect-URIs automatisch als Authorization-Endpunkte. Dort ist keine zusätzliche Post-Logout-URI erforderlich.

Warum benötigt Mailcow eigene Scope-Mappings?

Normales OpenID Connect liefert unter anderem:

Benutzername
Name
E-Mail-Adresse

Mailcow benötigt allerdings zwei zusätzliche Informationen:

Ist die E-Mail-Adresse bereits verifiziert?
Welche Mailbox-Vorlage soll verwendet werden?

Deshalb erstellen wir zwei eigene Scope Mappings.

Schritt 1 – Property Mapping „email“ erstellen

Melde dich zunächst als Administrator in authentik an.

Navigiere anschließend zu:

Customization
    └── Property Mappings

Klicke auf

New Property Mapping

und wähle

Scope Mapping

Nun vergeben wir den Scope-Namen

email

Hier verwendet Mailcow nicht das Standard-email-Mapping von authentik. Stattdessen wird ein eigenes Scope-Mapping benötigt, das zusätzlich den Claim email_verified aus den Benutzerattributen zurückliefert. Dieses benutzerdefinierte Mapping ersetzt später das Standard-email-Mapping im OIDC-Provider.

Expression

return {
    "email": request.user.email,
    "email_verified": True
}

Schritt 2 – Property Mapping „mailcow_template“

Erstelle anschließend ein weiteres Scope Mapping.

Verwende folgende Werte:

Name

mailcow_template

Scope

mailcow_template

Dieses Mapping sorgt dafür, dass Mailcow beim ersten Login weiß, welche Mailbox-Vorlage verwendet werden soll. Existiert kein Attribut, wird automatisch default genutzt.

Wir beziehen uns auf die Gruppen Attribute, da wir im zweiten Teil des Blogbeitrages eine Mailcow-User Gruppe erstellen.

Expression für Gruppen:

return {
    "mailcow_template": request.group_attributes(request).get("mailcow_template", "default"),
}

Expression für einen einzelnen Test-User:

return {
    "mailcow_template": request.user.attributes.get("mailcow_template", "default"),
}

Warum ist das Template wichtig?

Mailcow arbeitet intern mit sogenannten Mailbox Templates.

Diese definieren beispielsweise:

Quota
ActiveSync
CalDAV
CardDAV
POP3
IMAP
SMTP
Sieve
weitere Standardoptionen

Wenn später ein Benutzer automatisch erstellt wird, verwendet Mailcow genau dieses Template.

Dadurch müssen neue Benutzer nicht mehr manuell konfiguriert werden.

Schritt 3 – Benutzerattribute hinterlegen

Damit Mailcow weiß, dass ein Benutzer eine bestätigte Mailadresse besitzt und welches Template verwendet werden soll, müssen zwei Attribute gesetzt werden.

Nur für einen einzelnen Test-User notwendig! Steht ansonsten in den Gruppen-Attributen!

Öffne:

Directory
    └── Users

Wähle einen Benutzer aus.

Anschließend:

Edit User

Im Bereich Attributes ergänze:

email_verified: true
mailcow_template: default

Das ist nur nötig, wenn keine Gruppe erstellt werden soll, oder zu Testzwecken. Ansonsten werden im zweiten Teil diese Beitrags eine Gruppe erstellt, die die Attribute enthält.

Bedeutung der Attribute

email_verified

Mailcow akzeptiert ausschließlich Benutzer, deren E-Mail-Adresse als bestätigt markiert wurde.

Fehlt dieses Attribut, schlägt die Anmeldung häufig fehl.

mailcow_template

Dieses Attribut entscheidet, welches Mailbox-Template Mailcow verwendet.

Beispielsweise:

mailcow_template: default

oder

mailcow_template: premium

oder

mailcow_template: employees

Damit lassen sich unterschiedliche Benutzergruppen automatisch unterschiedlich konfigurieren.

Die Templates können im Admin-Interface von Mailcow, unter:

Email -> Konfiguration -> Mailboxen -> Vorlagen

angelegt oder angepasst werden.

Wichtiger Hinweis für bestehende Benutzer

Soll bereits vorhandene Mailboxen genutzt werden, muss die E-Mail-Adresse in authentik identisch mit der Mailbox-Adresse in Mailcow sein.

Beispiel:

Authentik:

max@example.com

Mailcow:

max@example.com

Stimmen die Adressen nicht überein, kann Mailcow den Benutzer nicht der vorhandenen Mailbox zuordnen. Soll Mailcow die Mailbox stattdessen beim ersten Login automatisch erstellen, muss die betreffende E-Mail-Domain bereits in Mailcow existieren.

Außerdem muss bei bereits vorhandenen Mailboxen, der im Postfach definierte Identity Provider, von „mailcow“ auf „Generic-OIDC“ umgestellt werden.

Dies ist unter:

Email -> Konfiguration -> Mailboxen -> rechte Seite bei der spezifischen Mailbox „Bearbeiten“

zu finden.

Fazit

Mit den bisherigen Schritten haben wir die Grundlage für eine erfolgreiche Integration von Mailcow Dockerized und authentik geschaffen. Wir haben die erforderlichen Property Mappings erstellt, die benötigten Benutzerattribute konfiguriert und authentik so vorbereitet, dass es als OpenID-Connect-Identity-Provider für Mailcow eingesetzt werden kann.

Im zweiten und abschließenden Teil richten wir den OIDC-Provider und die Application in authentik ein, konfigurieren Mailcow für die Anmeldung über OpenID Connect mit Single Sign-On und führen einen vollständigen Funktionstest durch. Außerdem werfen wir einen Blick auf das Auto-Provisioning neuer Benutzer, App-Passwörter für Mail-Clients sowie die häufigsten Fehlerquellen und deren Behebung.

Wenn wir auch Sie beim Aufbau eines eigenen Mailcow Servers oder dem Managed Hosting eines authentik Serves unterstützen können, dann nehmen Sie gerne Kontakt auf.

Heir geht es weiter zu Teil 2.

Josua Rieber

Admin Intelligence Ihre Linux Server Administratoren