­čöĺ­čöĹ External Identity Providers for User authentication

Moohoo - Gute Nachricht, Freunde!

Mit dem Nightly Branch ist es nun m├Âglich, einen externen Identity Provider als weitere Authentifizierungsquelle zu nutzen.
Daf├╝r nutzt die mailcow das OIDC Protokoll, um ausschlie├člich Mailbox User zu authentifizieren.
Um das zu erm├Âglichen, haben wir ein paar ├änderungen an der Art und Weise vorgenommen, wie die Authentifizierung funktioniert.

Lasst uns mal dar├╝ber sprechen, was sich ge├Ąndert hat, was wir uns dabei gedacht haben und was wir in Zukunft noch hinzuf├╝gen m├Âchten. Nat├╝rlich zeigen wir euch auch, wie ihr das neue Feature nutzen k├Ânnt.
Um die Dinge zu vereinfachen, verwende ich im weiteren Beitrag die Abk├╝rzung IdP f├╝r Identity Provider


Was wurde ge├Ąndert und warum?

Unser Ziel war es, dass man neben der bestehenden SQL Datenbank, gleichzeitig einen IdP als Authentifizierungsquelle nutzen kann. Dabei kann immer nur ein IdP konfiguriert werden und nicht mehrere.
Die mailcow muss jetzt also je nach User entscheiden k├Ânnen, welche Authentifizierungsquelle genutzt werden soll. Um das zu erm├Âglichen, haben wir ├änderungen an den Diensten mailcow UI (phpfpm), Dovecot und SOGo vorgenommen.

mailcow UI

Die gesamte Logik zur Authentifizierung haben wir auf den phpfpm-Dienst ausgelagert. F├╝r jeden User wird nun eine Authentifizierungsquelle hinterlegt, die zurzeit entweder mailcow, Keycloak oder Generic-OIDC sein kann. Beim Login nutzt mailcow dann die entsprechende Quelle zur Authentifizierung.

Dovecot

Dovecot hat bis jetzt ein custom LUA Script f├╝r die Authentifizierung genutzt, das SQL-Queries verwendet hat. Statt SQL-Queries, werden nun HTTP-Requests zu einem intern verf├╝gbaren PHP-Script verwendet.
User die sich ├╝ber den IdP authentifizieren, m├╝ssen App Passw├Ârter erstellen, damit weiterhin Mailclients wie Thunderbird genutzt werden k├Ânnen.
Es gibt noch eine weitere M├Âglichkeit, damit nicht extra App Passw├Ârter erstellt werden m├╝ssen. Die steht allerdings nur f├╝r den Keycloak Provider zur Verf├╝gung.
Dazu komme ich aber sp├Ąter.

SOGo

Viele haben sich vielleicht gefragt, warum der mailcow Login unter dem Root-Pfad angezeigt wird und nicht der SOGo Login. F├╝r den SOGo Login existiert schon l├Ąnger ein Proxy Auth Feature, welches aus der mailcow UI genutzt werden kann. Durch das Proxy Auth Feature k├Ânnen sich eingeloggte User zum SOGo weiterleiten lassen, ohne sich erneut anmelden zu m├╝ssen. Dadurch haben die User vorher noch die M├Âglichkeit, weitere Features zu nutzen, wie die Passwort├Ąnderung, App Passw├Ârter, tempor├Ąre Aliase, usw. Damit das Feature mehr hervorgehoben wird, haben wir deswegen die mailcow UI ├╝berarbeitet und einen auff├Ąlligen blauen Button direkt oben platziert, den wirklich niemand ├╝bersehen sollte. User, die den IdP nutzen, k├Ânnen sich nur ├╝ber die mailcow UI im SOGo einloggen. Ein direktes Einloggen ├╝ber SOGo funktioniert nicht.

Da ein direkter Login ├╝ber SOGo f├╝r IdP User nicht funktioniert, haben wir gleichzeitig die App-Links ├╝berarbeitet, damit es in Zukunft nicht zu Verwirrung f├╝hrt. App-Links k├Ânnen jetzt in den Einstellungen f├╝r den Login entweder versteckt oder angezeigt werden. Die standardm├Ą├čige Verlinkung auf SOGo im mailcow Login wird versteckt. Eingeloggte User sehen jedoch weiterhin alle Apps. Desweiteren kann man f├╝r eingeloggte User einen extra Link eintragen, wobei man hier mit %u eine Placeholder f├╝r den Usernamen hat. Z.B. k├Ânnen eingeloggte User per App-Link so an das Proxy Auth Script mit /sogo-auth.php?login=%u weitergeleitet werden.




Ideen f├╝r die Zukunft

F├╝r die Zukunft k├Ânnten wir in Erw├Ągung ziehen, dass ihr bei einzelnen Users einstellen k├Ânnt, wohin sie nach dem Login weitergeleitet werden sollen (mailcow oder SOGo).
Au├čerdem haben wir durch die ├ťberarbeitung der Authentifizierung die Login-Funktion in verschiedene Funktionen f├╝r Admins, Domain Admins, User und App-Passwort-Login aufgeteilt. Wir k├Ânnten dar├╝ber nachdenken, den Login f├╝r Admin, Domainadmin und User ├╝ber verschiedene Pfade bereitzustellen. Daf├╝r m├╝ssten wir dann aber auch die API in Admin-, Domainadmin- und User-API aufteilen.
Auf der Grundlage dieses Features k├Ânnten wir auch weitere OIDC-Provider hinzuf├╝gen, falls der Generic-OIDC-Provider nicht ausreicht oder sogar doch direkt einen LDAP Provider hinzuf├╝gen.


Wie nutze ich dieses Feature?

Vorab m├Âchte ich erw├Ąhnen, dass wir in unseren Tests bisher nur Keycloak als IdP getestet haben. Dennoch ist es m├Âglich, auch andere IdP’s (Generic-OIDC) einzurichten. Wenn ihr bereits einen anderen IdP wie zum Beispiel Authentik verwendet, w├╝rden wir uns ├╝ber Feedback freuen.

Die Voraussetzung f├╝r diese Anleitung ist, dass ihr bereits eine Keycloak-Instanz am Laufen habt.

F├╝r dieses Beispiel, nutzen wir folgendes Setup:

  • Keycloak als IdP
  • Keycloak-Instanz ist unter https://mail.cow.tld/auth erreichbar
  • mailcow-Instanz ist unter https://mail.cow.tld erreichbar
  • Als Domain f├╝r unsere E-Mails verwenden wir cow.tld
  • In Keycloak nutzen wir mailcow als Realm.

Keycloak Konfiguration

Schritt 1

Installiert euch die mailcow Nightly Version auf einer Testinstanz.
https://docs.mailcow.email/i_u_m/i_u_m_update/#best-practice-nightly-update

Schritt 2

Logt euch als Admin in Keycloak ein und wechselt zu eurem Realm oder erstellt euch einen.
In dem Realm erstellen wir nun einen neuen Client namens mailcow und konfigurieren Ihn wie folgt:

Schritt 3

Nach dem speichern des Clients, m├╝ssen wir f├╝r diesen noch ein User Attribute mit in den token claim aufnehmen. Das User Attribute nennt sich mailcow_template und durch folgende Einstellungen, wird dieses mit in den OIDC Endpoint /userinfo aufgenommen. Anhand dieses Attribute wird entschieden, wie die Mailbox konfiguriert wird (Quota, ACLs etc.)

Schritt 4

Nun k├Ânnen wir unter der Client Konfiguration den Client Secret kopieren und mit der mailcow weitermachen.




mailcow Konfiguration

Schritt 1

Loggt euch in die mailcow ein und navigiert zu System -> Konfiguration -> Zugang -> Identity Provider. F├╝llt die Felder entsprechend aus.
Die Keycloak Version steht im Admin Dashboard unter dem master Realm. Hier ist es eigentlich nur wichtig zu wissen, ob eine Version gr├Â├čer oder kleiner 20 benutzt wird, da mailcow dementsprechen den “openid” scope hinzugef├╝gen muss.
Das Attribute Mapping ist daf├╝r da, dass mailcow anhand des Keycloak User Attributes mailcow_template, die entsprechend gemappte Mailbox Vorlage anwendet. F├╝r das Beispiel habe ich keine extra Vorlage angelegt, weswegen wir ein Mapping auf die Default Vorlage einrichten.
Alles ab dem Attribute Mapping k├Ânnen wir erstmal ignorieren.

Schritt 2

Die Einstellungen k├Ânnen vor dem speichern getestet werden. Sollte der Test fehlschlagen, kontrolliert bitte, ob die mailcow die angegebene Server Url erreichen kann und die Angaben Realm, Client ID und Client Secret korrekt sind.




Test User anlegen

Wir k├Ânnen jetzt hingehen und einen User in Keycloak hinzuf├╝gen. Wechselt daf├╝r wieder in das Keycloak Admin Dashboard und w├Ąhlt euren Realm aus. Navigiert dann zu Users und f├╝gt den neuen User hinzu.

Danach geben wir noch an, dass der User eine default mailbox bekommt.

Zum Schluss nat├╝rlich noch dem neuen User unter dem Credentials Tab ein Passwort vergeben und fertig.

Der neue User existiert mit unserer jetzigen Konfiguration nicht direkt in mailcow. Dies geschieht aber automatisch beim ersten Login. Navigiert zum mailcow Login und klickt auf den SSO Button im Dropdown. Dadurch werdet Ihr zu Keycloak weitergeleitet. Sollte der Keycloak Login funktionieren und ihr landet trotzdem wieder bei dem mailcow Login mit einer Fehlermeldung, vergewissert euch bitte, dass die Domain existiert und das Mailboxen unter dieser Domain erstellt werden k├Ânnen.

Hat alles funktioniert, seid ihr nun eingeloggt und landet bei der neuen User Seite. Ich denke den “Login to webmail” Button kann man schlecht ├╝bersehen. Au├čerdem f├Ąllt auf, dass hier keine Konfigurationsm├Âglichkeiten f├╝r Passwort├Ąnderung oder 2FA angezeigt werden, da diese ├╝ber Keycloak konfiguriert werden.

Wenn Ihr mit diesem User nun einen Mailclient wie Thunderbird benutzen wollt, k├Ânnt Ihr euch unter App Passwords entsprechend ein Passwort erstellen.




IdP f├╝r existierende Mailbox User ├Ąndern

Ihr k├Ânnt den IdP f├╝r die bestehenden Mailbox User ganz einfach ├Ąndern. Ihr m├╝sst nur sicherstellen, dass der User im IdP existiert, dann die Mailbox in mailcow bearbeiten und den gew├╝nschten IdP ausw├Ąhlen. Wenn ihr sp├Ąter wieder zu mailcow als IdP zur├╝ckwechselt, wird das alte Passwort wiederverwendet.




Automatische User Provisionierung

Keycloak als IdP kann in der mailcow auch so konfiguriert werden, dass in einem benutzerdefinierten Intervall ├änderungen aller User kontrolliert werden. Damit k├Ânnen User automatisch angelegt werden und selbst bei nachtr├Ąglichen ├änderungen des mailcow_template, Attribute automatisch angepasst werden. Um das ganze konfigurieren zu k├Ânnen, ben├Âtigt der mailcow Client allerdings weitere Berechtigungen in Keycloak. Undzwar ben├Âtigt der Client die view-users Berechtigung. Damit k├Ânnen ├╝ber die Keycloak Admin REST-API alle Realm User abgefragt werden.

Schritt 1

Loggt euch als Admin in Keycloak ein, wechselt zu eurem Realm und bearbeitet den mailcow Client.

Schritt 2

Aktiviert in der mailcow UI unter Identity Provider Periodic Full Sync und Import Users. W├Ąhlt danach euren gew├╝nschten Intervall in Minuten und speichert. Periodic Full Sync checkt, ob sich das mailcow_template Attribute ge├Ąndert hat und passt die Mailbox dementsprechend an. Import Users checkt, ob neue User erstellt wurden und erstellt diese ebenfalls in mailcow.

Schritt 3

Unter System -> Information -> Protokolle -> Crontasks landen alle Logs bzgl. der automatischen User Provisionierung. Sollte also irgendwas nicht passen, findet ihr dort mehr Infos.

Mailpassword Flow

Wie im Infotext unter der Option beschrieben, kann der Mailpassword Flow genutzt werden, um den User mittels des Keycloak Attribute mailcow_password zu authentifizieren. Dieses Passwort kann auch direkt f├╝r die mailcow UI, sowie Mailclients verwendet werden.
Daf├╝r muss der mailcow Client die view-users Berechtigung haben, wie unter … beschrieben, und das Attribute mailcow_password muss in den token claim mit aufgenommen werden, wie unter … beschrieben. Dem User kann in Keycloak nun das Attribute mailcow_password hinzugef├╝gt werden. Das Passwort sollte gehashed werden und eines der folgenden Formate haben https://docs.mailcow.email/models/model-passwd/ Hier das Standard moohoo Passwort als Beispiel {SSHA256}K8eVJ6YsZbQCfuJvSUbaQRLr0HPLz5rC9IAp0PAFl0tmNDBkMDc0NDAyOTAxN2Rk




LDAP

In Keycloak k├Ânnt ihr in eurem Realm unter User Federation ein LDAP Provider anbinden.
https://www.keycloak.org/docs/latest/server_admin/#_ldap

Nach dem konfigurieren muss noch das mailcow_template Attribute gemapped werden. Wenn gew├╝nscht, kann mit der gleichen Prozedur auch das mailcow_password Attribute mappen.
Mit der folgenden Konfiguration, mappen wir das LDAP Attribute mailboxType auf das Keycloak Attribute mailcow_template. Ist kein Wert vorhanden, forcieren wir default als Wert f├╝r mailcow_template.




Zum Schluss

Die Authentifizierung wurde insgesamt stark ver├Ąndert. Achtet beim Testen besonders auf Sicherheitsl├╝cken.
Ansonsten k├Ânnen wir sagen: Viel Spa├č beim Testen! Wir freuen uns auf euer Feedback und eure Bug Reports.
­čÉ«



Bleibt gesund und happy Mailing!

Euer mailcow Team

0%