Serie: Mailcow Dockerized + authentik
Teil 2 von 2
In diesem Teil erstellen wir den OpenID-Connect-Provider in authentik, richten die Anwendung ein und konfigurieren anschließend Mailcow für die Anmeldung über Generic OIDC.

---

Rückblick

Im ersten Teil haben wir bereits:

• authentik vorbereitet
• die benötigten Scope Mappings erstellt
• die Benutzerattribute gesetzt
• die Voraussetzungen für OIDC geschaffen

Jetzt verbinden wir beide Systeme miteinander.

---

Architektur der OIDC-Anbindung

Die Kommunikation zwischen Mailcow und authentik läuft über den OpenID-Connect-Standard.

┌──────────────┐
│   Benutzer                    │
└──────--───────┘
       │
       ▼
┌─────────────────────────┐
│     Mailcow Webmail                                │
└──────────--──────────────┘
           │
           │ Redirect
           ▼
┌─────────────────────────┐
│       authentik                                            │
│ Identity Provider (IdP)                              │
└──────────--──────────────┘
           │
           │ ID-Token
           ▼
┌─────────────────────────┐
│        Mailcow                                            │
└─────────────────────────┘

---

Schritt 4 – OIDC Provider erstellen

Melde dich in authentik als Administrator an.

Navigiere anschließend zu:

Applications
    └── Providers

Klicke auf

New Provider

und wähle

OAuth2/OpenID Provider

---

Allgemeine Einstellungen

Vergib einen Namen.

Beispielsweise:

Provider for Mailcow

---

Authorization Flow

Für die meisten Self-Hosting- oder Unternehmensumgebungen wird default-provider-authorization-implicit-consent verwendet, da es das Benutzererlebnis verbessert und keine unnötigen Bestätigungsdialoge erzeugt.

default-provider-authorization-implicit-consent (Authorize Application)

---

Client Type

Als Client-Typ wird gewählt:

Confidential

Mailcow arbeitet als vertraulicher Client und authentifiziert sich später mit einer Client-ID und einem Client-Secret.

Die Werte „Client-ID“ und „Client-Secret“ werden später in Mailcow benötigt und müssen notiert werden!

---

Redirect URI konfigurieren

Mailcow erwartet eine Callback-Adresse.

Diese lautet:

https://mail.example.com

Ersetze selbstverständlich deine eigene Domain.

Bei aktuellen authentik-Versionen sollte die Redirect URI als Strict → Authorization eingetragen werden. Dadurch akzeptiert authentik ausschließlich exakt diese Rücksprungadresse.

---

Signing Key

Verwende den Standard Signing Key von authentik oder einen bereits vorhandenen Schlüssel.

Nur wenn spezielle Compliance-Vorgaben existieren, sollte hierfür ein eigener Schlüssel erzeugt werden.

---

Token-Lebensdauer

Für die meisten Installationen können die Standardwerte übernommen werden.

Zu finden unter: Advanced protocol settings

Beispielsweise:

Einstellung	Empfehlung
Access Token	Standard
Refresh Token	Standard
ID Token	Standard

Nur wenn interne Sicherheitsrichtlinien kürzere Laufzeiten verlangen, sollten diese angepasst werden.

---

Scopes auswählen

Nun werden die benötigten Scopes ausgewählt. Diese sind unter:

Advanced protocol settings

zu finden.

Standardmäßig aktiviert:

OpenID 'email'
OpenID 'openid'
OpenID 'profile'

Zunächst entfernen:

OpenID 'email'

Zusätzlich hinzufügen:

email
mailcow_template

Achte darauf, dass das zuvor erstellte benutzerdefinierte email-Scope verwendet wird, damit neben der E-Mail-Adresse auch email_verified übertragen wird.

Standard:

Angepasst:

Speichere nun den Provider durch den Button „“Create“.

---

Schritt 5 – Application erstellen

Nun erstellen wir die eigentliche Anwendung.

Navigiere zu

Applications

und anschließend klicke auf

New Application (Drop-Down-Menü!)- with Existing Provider...

---

Name

Beispielsweise

Mailcow

---

Slug

mailcow

---

Provider

Hier wird der eben erstellte Provider ausgewählt.

In diese Anleitung:

Provider for Mailcow

---

Launch URL

Optional kann hier eingetragen werden:

https://mail.example.com

Ansonsten wird die Information aus dem zuvor erstellten Provider verwendet.

Speichere nun die Applikation durch den Button „“Create Application“.

---

Zuweisung über User oder Gruppen

Jetzt erfolgt die Konfiguration der User oder Gruppen, welche auf die Applikation zugreifen dürfen.

Typische Varianten sind:

• Alle Benutzer
• Nur Mitglieder der Gruppe „Mailcow-User“
• Nur Administratoren
• Nur bestimmte Organisationseinheiten

Gerade in größeren Umgebungen empfiehlt sich die Freigabe über Gruppen. Neue Mitarbeiter erhalten dadurch automatisch Zugriff, sobald sie Mitglied der entsprechenden Gruppe werden.

Navigiere zu:

Directory
    └── Groups

Erstelle nun eine neue Gruppe, mit den Attributen:

email_verified: true,
mailcow_template: default

Das Kommata nach „email_verified: true“ ist NICHT optional!

Wähle „New Group“

Wähle einen passenden Namen, hier „Mailcow-User“

Trage die Attributen von oben ein

Füge abschließend die gewünschten User der Gruppe hinzu (bestehende User wurden auf dem Bild ausgeblendet!):

Damit ist die Konfiguration bei Authentik abgeschlossen.

---

Schritt 6 – OIDC in Mailcow aktivieren

Jetzt wechseln wir in die Mailcow-Administration.

Navigiere zu:

System
    └── Configuration

Anschließend:

Access 
    └── Identity Provider

Dort befindet sich der Bereich

Identity Provider

---

Generic OIDC aktivieren

Wähle zunächst bei Identity Provider

Generic OpenID Connect

Dadurch erscheinen die weiteren Eingabefelder.

---

Authorization Endpunkt

Beispielsweise:

https://auth.example.com/application/o/authorize/

Alle Pfade werden vom zuvor erstellten OIDC-Provider vorgegeben.

In Authentik zu finden unter:

Applications
    └── Providers
                   └── Provider for Mailcow

Die Übersichtsseite enthält alle Angaben die benötigt werden.

---

Token Endpunkt

https://auth.example.com/application/o/token/

---

User info Endpunkt

https://auth.example.com/application/o/userinfo/

---

Client ID

Hier wird die notierte Client-ID aus authentik eingefügt.

xxxxxxxxxxxxxxxxxxxxxxxx

---

Client Secret

Hier kommt das notierte Client-Secret hinein.

xxxxxxxxxxxxxxxxxxxxxxxx

---

Redirect Url

https://mail.example.com

---

Client Scopes

Mailcow benötigt folgende Scopes:

openid profile email mailcow_template

Die Reihenfolge spielt dabei keine Rolle, alle benötigten Scopes müssen jedoch enthalten sein.

---

Attribut Mapping

Mailcow kann Benutzer automatisch anlegen, sobald sie sich das erste Mal anmelden.

Dafür müssen drei Voraussetzungen erfüllt sein:

• Die E-Mail-Domain existiert bereits in Mailcow.
• Das Attribut mailcow_template ist im Token enthalten.
• Das Attribut Mapping wurde richtig konfiguriert.

Ein erster Verbindungstest zu Authentik kann auf der Seite durchgeführt werden.

Speichere anschließend die Konfiguration.

---

Verbindungstest

Öffne anschließend die Mailcow-Anmeldeseite.

Neben der klassischen Anmeldung sollte nun ein zusätzlicher Button erscheinen.

Single Sign-On

Beim Anklicken solltest du auf die Login-Seite von authentik weitergeleitet werden.

Nach erfolgreicher Anmeldung erfolgt automatisch die Rückleitung zu Mailcow und der Login in das hinterlegte Postfach des Authentik-Users.

---

Häufige Fehler bis hierhin

Ungültige Redirect-URI

Wenn authentik eine Fehlermeldung wie Invalid redirect URI anzeigt, stimmt die in Mailcow verwendete Rücksprungadresse nicht exakt mit der im OIDC-Provider hinterlegten Redirect-URI überein. Schon ein fehlender Slash oder eine abweichende URL führt zur Ablehnung.

---

Client-Secret stimmt nicht

Ein häufiges Problem nach Änderungen am Provider ist ein veraltetes Client-Secret. Wird ein neues Secret generiert, muss es auch in Mailcow aktualisiert werden.

---

Fehlende Scopes

Fehlen die Scopes email oder mailcow_template, erhält Mailcow nicht alle benötigten Claims. Das führt häufig dazu, dass Benutzer nicht korrekt zugeordnet oder automatisch erstellt werden können.

---

Sicherheits-Tipps

HTTPS erzwingen

OIDC sollte ausschließlich über HTTPS betrieben werden.

---

App-Passwörter für Thunderbird, Outlook und Smartphones verwenden

Ein häufiger Irrtum besteht darin, dass nach der Einführung von Single Sign-on auch IMAP, SMTP oder ActiveSync über OpenID Connect funktionieren.

Das ist derzeit nicht der Fall.

Mail-Clients wie:

• Thunderbird
• Outlook
• Apple Mail
• K-9 Mail
• FairEmail
• iOS Mail
• Android Mail

verwenden weiterhin klassische Mail-Protokolle.

Für diese Protokolle empfiehlt Mailcow die Nutzung von App-Passwörtern.

Dadurch ergeben sich mehrere Vorteile:

• Das eigentliche Passwort bleibt unbekannt.
• Ein kompromittiertes Gerät kann einzeln gesperrt werden.
• App-Passwörter lassen sich jederzeit widerrufen.
• Mehrere Geräte können unterschiedliche Passwörter verwenden.

---

Multi-Faktor-Authentifizierung für das Single Sign-On

Ein großer Vorteil der Integration besteht darin, dass MFA vollständig von authentik übernommen wird.

Dadurch profitieren sämtliche angebundenen Anwendungen gleichzeitig von:

• TOTP
• WebAuthn
• FIDO2
• Passkeys
• Hardware Security Keys
• Recovery Codes

Mailcow selbst benötigt hierfür keine eigene Konfiguration.

---

Gruppen statt Einzelrechte

Berechtigungen lassen sich dadurch deutlich einfacher verwalten.

---

Reverse Proxy korrekt konfigurieren

Wer authentik oder Mailcow hinter einem Reverse Proxy wie NGINX Proxy Manager, Traefik oder HAProxy betreibt, sollte sicherstellen, dass die Header X-Forwarded-Proto, X-Forwarded-Host und Host korrekt an die jeweiligen Container weitergereicht werden. Fehler in der Proxy-Konfiguration zählen zu den häufigsten Ursachen für Redirect-Probleme oder ungültige Callback-URLs.

---

Regelmäßige Updates

Sowohl Mailcow als auch authentik entwickeln sich sehr aktiv weiter. Halte beide Systeme aktuell und überprüfe nach größeren Versionssprüngen die offiziellen Release Notes auf Änderungen an der OIDC-Integration oder neuen Sicherheitsfunktionen.

---

Fazit

Die Integration von Mailcow Dockerized mit authentik Single Sign-On schafft eine moderne und zentrale Authentifizierungsplattform für deine E-Mail-Infrastruktur. Benutzer profitieren von einem komfortablen Single Sign-on, während Administratoren Passwörter, Multi-Faktor-Authentifizierung und Zugriffsrichtlinien an einer zentralen Stelle verwalten können.

Besonders in Umgebungen mit mehreren Self-Hosted-Anwendungen entfaltet authentik seine Stärken. Neue Benutzer werden einmalig angelegt, Gruppen und Rollen zentral gepflegt und können – je nach Konfiguration – automatisch mit einer passenden Mailbox in Mailcow ausgestattet werden. Gleichzeitig bleibt Mailcow für die eigentliche Mailverwaltung verantwortlich und konzentriert sich auf Domains, Postfächer, Quotas und Maildienste.

Mit den in dieser zweiteiligen Anleitung beschriebenen Schritten erhältst du eine wartungsarme, sichere und zukunftsfähige Lösung, die sich problemlos erweitern lässt – beispielsweise um weitere Anwendungen wie Nextcloud, Vaultwarden, Grafana, Proxmox VE oder Portainer, die ebenfalls über authentik angebunden werden können.

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.