diff --git a/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-generic-oidc.de.md b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-generic-oidc.de.md new file mode 100644 index 000000000..4e7086cf8 --- /dev/null +++ b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-generic-oidc.de.md @@ -0,0 +1,78 @@ +### **Konfigurieren** + +Um einen **Identity Provider** zu konfigurieren, melde Sie sich als Administrator in der *mailcow UI* an, navigieren Sie zu +`System > Konfiguration > Zugriff > Identity Provider` und wählen Sie **Generic-OIDC** aus dem Dropdown-Menü aus. + +* `Authorization Endpoint`: Die URL des Authorization Endpoints des Provider's. +* `Token Endpoint`: Die URL des Token Endpoints des Provider's. +* `User Info Endpoint`: Die URL des User Info Endpoint des Provider's. +* `Client ID`: Die Client-ID, die dem mailcow Client im OIDC-Provider zugewiesen wurde. +* `Client Secret`: Das Client-Secret, das dem mailcow Client im OIDC-Provider zugewiesen wurde. +* `Redirect URL`: Die Redirect-URL, die der OIDC-Provider nach der Authentifizierung verwendet. Diese sollte auf die mailcow UI verweisen. Beispiel: `https://mail.mailcow.tld` +* `Client Scopes`: Gibt die während der Authentifizierung angeforderten **OIDC-Scopes** an. Die Standard-Scopes sind `openid profile email mailcow_template`. +* `Attribut Mapping`: + * `Attribut`: Definiert den Attributwert, der zugeordnet werden soll. + * `Vorlage`: Gibt an, welche Mailbox-Vorlage für den definierten Attributwert angewendet werden soll. +* `Ignoriere SSL Fehler`: Wenn aktiviert, wird die Überprüfung des SSL-Zertifikats deaktiviert. + +--- + +### **Automatische Benutzerbereitstellung** + +Wenn ein Benutzer in **mailcow** nicht existiert und sich über die **mailcow UI** anmeldet, wird er **automatisch erstellt**, sofern ein passendes **Attribut Mapping** konfiguriert ist. + +#### **Funktionsweise** +1. Bei der Anmeldung initialisiert **mailcow** einen **Authorization Code Flow** und ruft bei Erfolg das **OIDC-Token** des Benutzers ab. +2. **mailcow** sucht dann im User Info Endpoint nach dem Wert von `mailcow_template` und ruft ihn ab. +3. Wenn der Wert mit einem Attribut in dem **Attribut Mapping** übereinstimmt, wird die entsprechende **Mailbox-Vorlage** angewendet. + +#### **Beispielkonfiguration** +- Der Benutzer hat das Attribut `mailcow_template` mit dem Wert `default`, das vom **User Info Endpoint** abgerufen werden kann. +- Unter **Attribut Mapping** setzt du `Attribut` auf `default` und wählst eine geeignete **Mailbox-Vorlage** aus. + +#### **Updates bei der Anmeldung** +Jedes Mal, wenn sich ein Benutzer über die **mailcow UI** anmeldet, überprüft **mailcow**, ob sich die zugewiesene **Mailbox-Vorlage** geändert hat. Falls ja, werden die Mailbox-Einstellungen entsprechend aktualisiert. + +--- + +### **Authentifizierungsquelle für bestehende Benutzer ändern** + +Nachdem ein **Generic-OIDC Identity Provider** konfiguriert wurde, kann die Authentifizierungsquelle bestehender Benutzer von **mailcow** auf **Generic-OIDC** umgestellt werden. + +1. Navigiere Sie zu `E-Mail > Konfiguration > Mailboxen`. +2. Bearbeiten Sie den Benutzer. +3. Wählen Sie im **Identity Provider**-Dropdown **Generic-OIDC** aus. +4. Speichern Sie die Änderungen. + +!!! info "Hinweis" + + Das bestehende SQL-Passwort wird **nicht überschrieben**. Falls die Authentifizierungsquelle wieder auf **mailcow** umgestellt wird, kann der Benutzer sich weiterhin mit seinem vorherigen Passwort anmelden. + +--- + +### **Authentifizierung für externe Mail-Clients (IMAP, SIEVE, POP3, SMTP)** + +Bevor Benutzer externe Mail-Clients nutzen können, müssen sie sich zunächst in die mailcow UI einloggen und zu den **Mailbox-Einstellungen** navigieren. +Im Tab **App-Passwörter** können sie ein neues App-Passwort erstellen, das anschließend zur Authentifizierung im externen Mail-Client verwendet werden kann. + +--- + +### **Fehlersuche** + +Wenn Benutzer sich nicht anmelden können, überprüfen Sie zuerst die Logs unter: `System > Information > Logs > mailcow UI`. +Danach können Sie diesen Schritten zur Fehlerbehebung folgen: + +1. **Verbindung testen** + - Gehen Sie zu `System > Konfiguration > Zugriff > Identity Provider`. + - Klicken Sie den **Verbindung Testen** Button und stellen Sie sicher, dass er erfolgreich abgeschlossen wird. + +2. **Client-Daten überprüfen** + - Gehen Sie zu `System > Konfiguration > Zugriff > Identity Provider`. + - Stelle sicher, dass **Client-ID** und **Client-Secret** mit den Daten des OIDC-Provider's übereinstimmen. + +3. **Mail Domain des Benutzers prüfen** + - Stellen Sie sicher, dass die Domain des Benutzers in mailcow existiert. + - Überprüfen Sie, ob die Domain durch **"Max. Mailboxanzahl"** oder **"Domain Speicherplatz gesamt (MiB)"** eingeschränkt ist. + +3. **Attribut Mapping prüfen** + - Stellen Sie sicher, dass eine passendes **Attribut Mapping** für die Benutzer konfiguriert ist. diff --git a/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-generic-oidc.en.md b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-generic-oidc.en.md new file mode 100644 index 000000000..d638a29da --- /dev/null +++ b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-generic-oidc.en.md @@ -0,0 +1,75 @@ +### **Configure** + +To add or edit your **Identity Provider** configuration, log in to your *mailcow UI* as administrator, go to `System > Configuration > Access > Identity Provider` and select **Generic-OIDC** from the Identity Provider dropdown. + +* `Authorization Endpoint`: The provider's authorization server URL. +* `Token Endpoint`: The provider's token server URL. +* `User Info Endpoint`: The provider's user info server URL. +* `Client ID`: The Client ID assigned to mailcow Client in OIDC provider. +* `Client Secret`: The Client Secret assigned to the mailcow client in OIDC provider. +* `Redirect URL`: The redirect URL that OIDC provider will use after authentication. This should point to your mailcow UI. Example: `https://mail.mailcow.tld` +* `Client Scopes`: Specifies the OIDC scopes requested during authentication. The default scopes are `openid profile email mailcow_template` +* `Attribute Mapping`: + * `Attribute`: Defines the attribute value that should be mapped. + * `Template`: Specifies which mailbox template should be applied for the defined attribute value +* `Ignore SSL Errors`: If enabled, SSL certificate validation is bypassed. + +--- + +### **Automatic User Provisioning** +If a user does not exist in **mailcow** and logs in via **mailcow UI**, the user will be **automatically created**, provided that a matching **attribute mapping** is configured. + +#### **How It Works** +1. On login, **mailcow** initializes an **Authorization Code Flow** and, if successful, retrieves the user's **OIDC token**. +2. **mailcow** then looks for the **`mailcow_template`** value in the user info and retrieves it. +3. If the value matches an attribute defined in the **Attribute Mapping**, the corresponding **mailbox template** is applied. + +#### **Example Configuration** +- The user has an attribute **`mailcow_template`** with the value **`default`**, which can be retrieved from the **User Info Endpoint**. +- Under **Attribute Mapping**, set **`Attribute`** to **`default`** and select an appropriate **mailbox template**. + +#### **Updates on Login** +Each time a user logs in via **mailcow UI**, **mailcow** checks if the assigned template has changed. If so, it updates the mailbox settings accordingly. + +--- + +### **Change the Authentication Source for Existing Users** + +Once you have configured an **Generic-OIDC Identity Provider**, you can change the authentication source for existing users from **mailcow** to **Generic-OIDC**. + +1. Navigate to **`E-Mail > Configuration > Mailboxes`**. +2. Edit the user. +3. From the **Identity Provider** dropdown, select **Generic-OIDC**. +4. Save the changes. + +!!! info "Notice" + + The existing SQL password is **not overwritten**. If you switch the authentication source back to **mailcow**, the user will be able to log in with their previous password. + +--- + +### **Authentication for External Mail Clients (IMAP, SIEVE, POP3, SMTP)** + +Before users can use external mail clients, they must first log in to the mailcow UI and navigate to the **Mailbox Settings**. +In the **App Passwords** tab, they can generate a new app password, which must then be used for authentication in the external mail client. + +--- + +### **Troubleshooting** + +If users are unable to log in, follow these steps to diagnose and resolve the issue: + +1. **Test Connection** + - Navigate to **`System > Configuration > Access > Identity Provider`**. + - Run the **Connection Test** and ensure it completes successfully. + +1. **Verfiy Client details** + - Navigate to **`System > Configuration > Access > Identity Provider`**. + - verify that Client ID and Client Secret matches data of OIDC Provider + +3. **Verify the User’s Mail Domain** + - Ensure the user’s mail domain exists in mailcow. + - Check if the domain is limited by **"Max. possible mailboxes"** or **"Domain quota"**. + +4. **Confirm Attribute Mapping** + - Make sure a matching **Attribute Mapping** is configured for the users. diff --git a/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.de.md b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.de.md new file mode 100644 index 000000000..9b2be716f --- /dev/null +++ b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.de.md @@ -0,0 +1,123 @@ +### **Konfigurieren** + +Um einen **Identity Provider** zu konfigurieren, melden Sie sich als Administrator in der *mailcow UI* an, navigieren Sie zu +`System > Konfiguration > Zugriff > Identity Provider` und wählen Sie **Keycloak** aus dem Dropdown-Menü aus. + +* `Server URL`: Die Basis-URL Ihres Keycloak-Servers. +* `Realm`: Das Keycloak-Realm, in dem der mailcow Client konfiguriert ist. +* `Client ID`: Die Client-ID, die dem mailcow Client in Keycloak zugewiesen wurde. +* `Client Secret`: Das Client-Secret des mailcow Clients in Keycloak. +* `Redirect URL`: Die Redirect-URL, die Keycloak nach der Authentifizierung verwendet. Diese sollte auf die mailcow UI verweisen. Beispiel: `https://mail.mailcow.tld` +* `Version`: Die verwendete Keycloak-Version. +* `Attribut Mapping`: + * `Attribut`: Definiert den Attributwert, der zugeordnet werden soll. + * `Vorlage`: Bestimmt, welche Mailbox-Vorlage für den definierten LDAP-Attributwert angewendet werden soll. +* `Mailpassword Flow`: Wenn aktiviert, versucht mailcow, Benutzeranmeldeinformationen über die **Keycloak Admin REST API** zu validieren, anstatt sich ausschließlich auf den Authorization Code Flow zu verlassen. + * Dies erfordert, dass der Benutzer in Keycloak ein **mailcow_password**-Attribut gesetzt hat. Das **mailcow_password** sollte ein gehashtes Passwort enthalten. + * Der mailcow Client in Keycloak muss über ein **Service Account** und die Berechtigung **view-users** verfügen. +* `Ignoriere SSL Fehler`: Wenn aktiviert, wird die Überprüfung des SSL-Zertifikats deaktiviert. +* `Vollsynchronisation`: Wenn aktiviert, synchronisiert mailcow regelmäßig alle Benutzer aus Keycloak. +* `Importiere Benutzer`: Wenn aktiviert, werden neue Benutzer automatisch aus Keycloak in mailcow importiert. +* `Sync / Import interval (min)`: Definiert das Zeitintervall (in Minuten) für die Option "Vollsynchronisation" und die Option "Importiere Benutzer". + +--- + +### **Automatische Benutzerbereitstellung** + +Wenn ein Benutzer in **mailcow** nicht existiert und sich über die **mailcow UI** anmeldet, wird er **automatisch erstellt**, sofern ein passendes **Attribut Mapping** konfiguriert ist. + +#### **Funktionsweise** +1. Bei der Anmeldung initialisiert **mailcow** einen **Authorization Code Flow** und ruft bei Erfolg das **OIDC-Token** des Benutzers ab. +2. **mailcow** sucht dann im User Info Endpoint nach dem Wert von **`mailcow_template`** und ruft ihn ab. +3. Wenn der Wert mit einem Attribut in dem **Attribut Mapping** übereinstimmt, wird die entsprechende **Mailbox-Vorlage** angewendet. + +#### **Beispielkonfiguration** +- Der Benutzer hat das Attribut **`mailcow_template`** mit dem Wert **`default`**, das vom User Info Endpoint abgerufen werden kann. +- Unter **Attribut Mapping** wird das **`Attribut`** auf **`default`** gesetzt und eine geeignete **Mailbox-Vorlage** ausgewählt. + +#### **Updates bei der Anmeldung** +Jedes Mal, wenn sich ein Benutzer über die **mailcow UI** anmeldet, überprüft **mailcow**, ob sich die zugewiesene **Mailbox-Vorlage** geändert hat. Falls ja, werden die Mailbox-Einstellungen entsprechend aktualisiert. + +#### **Import und Updates über Crontasks** +!!! warning "Voraussetzung" + + Dies erfordert, dass **mailcow** Zugriff auf die **Keycloak Admin REST API** hat. + Stellen Sie sicher, dass der **mailcow Client** ein **Service Account** hat und diesem die Service Account Role **view-users** zugewiesen wurde. + +Wenn **Importiere Benutzer** aktiviert ist, wird ein geplanter Cron-Job ausgeführt, der Benutzer aus Keycloak nach mailcow importiert. Dies erfolgt in dem festgelegten **Sync / Import interval (min)**. + +Wenn **Vollsynchronisation** aktiviert ist, aktualisiert der Cron-Job auch bestehende Benutzer im festgelegten **Sync / Import interval (min)** und übernimmt Änderungen aus Keycloak in mailcow. + +Logs zu Importen und Synchronisationen können unter `System > Information > Logs > Crontasks` eingesehen werden. + +--- + +### **Mailpassword Flow** +!!! warning "Voraussetzung" + + Dies erfordert, dass **mailcow** Zugriff auf die **Keycloak Admin REST API** hat. + Stellen Sie sicher, dass der **mailcow Client** ein **Service Account** hat und diesem die Service Account Role **view-users** zugewiesen wurde. + +Der **Mailpassword Flow** ist eine direkte Authentifizierungsmethode, die **nicht** das **OIDC-Protokoll** verwendet. Sie dient als Alternative zum **Authorization Code Flow**. + +Mit dem **Mailpassword Flow** funktioniert die automatische Benutzerbereitstellung auch für Anmeldungen über **Mail-Protokolle** (IMAP, SIEVE, POP3, SMTP). + +#### **Funktionsweise** +1. Bei der Anmeldung ruft **mailcow** die Benutzerattribute über die **Keycloak Admin REST API** ab. +2. **mailcow** sucht nach dem **`mailcow_password`**-Attribut. +3. Der Wert von **`mailcow_password`** muss ein [**kompatibles, gehashtes Passwort**](../../models/model-passwd.md) enthalten, das zur Authentifizierung verwendet wird. + +Dies gewährleistet eine nahtlose Authentifizierung und automatische Mailbox-Erstellung für Anmeldungen über mailcow UI und Mail-Protokolle. + +#### **Generieren eines BLF-CRYPT-gehashten Passworts** +Der folgende Befehl erstellt ein bcrypt-gehashtes Passwort und fügt `{BLF-CRYPT}` als Präfix hinzu: + +```bash +mkpasswd -m bcrypt | sed 's/^/{BLF-CRYPT}/' +``` + +--- + +### **Authentifizierungsquelle für bestehende Benutzer ändern** + +Nachdem ein **Keycloak Identity Provider** konfiguriert wurde, kann die Authentifizierungsquelle bestehender Benutzer von **mailcow** auf **Keycloak** umgestellt werden. + +1. Navigieren Sie zu **`E-Mail > Konfiguration > Mailboxen`**. +2. Bearbeiten Sie den Benutzer. +3. Wählen Sie im **Identity Provider**-Dropdown **Keycloak** aus. +4. Speichern Sie die Änderungen. + +!!! info "Hinweis" + + Das bestehende SQL-Passwort wird **nicht überschrieben**. Falls die Authentifizierungsquelle wieder auf **mailcow** umgestellt wird, kann der Benutzer sich wieder mit seinem vorherigen Passwort anmelden. + +--- + +### **Authentifizierung für externe Mail-Clients (IMAP, SIEVE, POP3, SMTP)** +!!! info "Hinweis" + + Dies gilt nicht zwingend für Benutzer, die den Mailpassword Flow verwenden. + +Bevor Benutzer externe Mail-Clients nutzen können, müssen sie sich zunächst in die mailcow UI einloggen und zu den **Mailbox-Einstellungen** navigieren. +Im Tab **App-Passwörter** können sie ein neues App-Passwort erstellen, das anschließend zur Authentifizierung im externen Mail-Client verwendet werden kann. + +--- + +### **Fehlersuche** + +Wenn Benutzer sich nicht anmelden können, überprüfen Sie zuerst die Logs unter: `System > Information > Logs > mailcow UI`. +Danach können Sie diesen Schritten zur Fehlerbehebung folgen: + +1. **Verbindung testen** + - Gehen Sie zu **`System > Konfiguration > Zugriff > Identity Provider`**. + - Klicken Sie den **Verbindung Testen** Button und stellen Sie sicher, dass er erfolgreich abgeschlossen wird. + +2. **Mail Domain des Benutzers prüfen** + - Stellen Sie sicher, dass die Domain des Benutzers in mailcow existiert. + - Überprüfen Sie, ob die Domain durch **"Max. Mailboxanzahl"** oder **"Domain Speicherplatz gesamt (MiB)"** eingeschränkt ist. + +3. **Attribut Mapping prüfen** + - Stellen Sie sicher, dass eine passendes **Attribut Mapping** für die Benutzer konfiguriert ist. + +Falls Probleme mit **`Vollsynchronisation`** oder **`Importiere Benutzer`** auftreten, überprüfen Sie die Logs unter: +`System > Information > Logs > Crontasks`. diff --git a/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.en.md b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.en.md new file mode 100644 index 000000000..b63b2e597 --- /dev/null +++ b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.en.md @@ -0,0 +1,120 @@ +### **Configure** + +To add or edit your **Identity Provider** configuration, log in to your *mailcow UI* as administrator, go to `System > Configuration > Access > Identity Provider` and select **Keycloak** from the Identity Provider dropdown. + +* `Server URL`: The base URL of your Keycloak server. +* `Realm`: The Keycloak realm where the mailcow client is configured. +* `Client ID`: The Client ID assigned to mailcow Client in Keycloak. +* `Client Secret`: The Client Secret assigned to the mailcow client in Keycloak. +* `Redirect URL`: The redirect URL that Keycloak will use after authentication. This should point to your mailcow UI. Example: `https://mail.mailcow.tld` +* `Version`: Specifies the Keycloak version. +* `Attribute Mapping`: + * `Attribute`: Defines the attribute value that should be mapped. + * `Template`: Specifies which mailbox template should be applied for the defined LDAP attribute value +* `Mailpassword Flow`: If enabled, mailcow will attempt to validate user credentials using the **Keycloak Admin REST API** instead of relying solely on the Authorization Code Flow. + * This requires that the user has a **mailcow_password** attribute set in Keycloak. **mailcow_password** should contain a hashed password + * The mailcow client in Keycloak must have a Service Account and permission to view-users. +* `Ignore SSL Errors`: If enabled, SSL certificate validation is bypassed. +* `Periodic Full Sync`: If enabled, mailcow periodically performs a full sync of all users from Keycloak. +* `Import Users`: If enabled, new users are automatically imported from Keycloak into mailcow. +* `Sync / Import Interval (min)`: Defines the time interval (in minutes) for periodic synchronization and user imports. + +--- + +### **Automatic User Provisioning** +If a user does not exist in **mailcow** and logs in via the **mailcow UI**, the user will be **automatically created**, provided that a matching **attribute mapping** is configured. + +#### **How It Works** +1. On login, **mailcow** initializes an **Authorization Code Flow** and, if successful, retrieves the user's **OIDC token**. +2. **mailcow** then looks for the **`mailcow_template`** value in the user info and retrieves it. +3. If the value matches an attribute defined in the **Attribute Mapping**, the corresponding **mailbox template** is applied. + +#### **Example Configuration** +- The user has an attribute **`mailcow_template`** with the value **`default`**, which can be retrieved from the **User Info Endpoint**. +- Under **Attribute Mapping**, set **`Attribute`** to **`default`** and select an appropriate **mailbox template**. + +#### **Updates on Login** +Each time a user logs in via the **mailcow UI**, **mailcow** checks if the assigned **template** has changed. If so, it updates the mailbox settings accordingly. + +#### **Import and Updates via Crontask** +!!! warning "Prerequisite" + + This requires **mailcow** to have access to the **Keycloak Admin REST API**. + Make sure the **mailcow Client** has an Service Account and the Service account role **view-users**. + +If **Import Users** is enabled, a scheduled cron job will automatically import users from Keycloak to mailcow at the specified **Sync / Import Interval (min)**. + +If **Periodic Full Sync** is enabled, the cron job will also update existing users at the specified **Sync / Import Interval (min)**, ensuring that any changes in LDAP are applied to their corresponding mailboxes in mailcow. + +Check the logs for imports and sync updates under `System > Information > Logs > Crontasks`. + +--- + +### **Mailpassword Flow** +!!! warning "Prerequisite" + + This requires **mailcow** to have access to the **Keycloak Admin REST API**. + Make sure the **mailcow Client** has an Service Account and the Service account role **view-users**. + +The **Mailpassword Flow** is a direct authentication method that does **not** use the **OIDC Protocol**. It serves as an alternative to the **Authorization Code Flow**. + +With the **Mailpassword Flow**, automatic user provisioning also works for logins via **mail protocols** (IMAP, SIEVE, POP3, SMTP). + +#### **How It Works** +1. On login, **mailcow** uses the **Keycloak Admin REST API** to retrieve the user’s attributes. +2. **mailcow** looks for the **`mailcow_password`** attribute. +3. The **`mailcow_password`** value should contain a [**compatible hashed password**](../../models/model-passwd.md), which will be used for verification. + +This ensures seamless authentication and mailbox creation for both UI and mail protocol logins. + +#### **Generate a BLF-CRYPT Hashed Password** +The following command creates a bcrypt-hashed password and prefixes it with `{BLF-CRYPT}`: + +```bash +mkpasswd -m bcrypt | sed 's/^/{BLF-CRYPT}/' +``` + +--- + +### **Change the Authentication Source for Existing Users** + +Once you have configured an **Keycloak Identity Provider**, you can change the authentication source for existing users from **mailcow** to **Keycloak**. + +1. Navigate to **`E-Mail > Configuration > Mailboxes`**. +2. Edit the user. +3. From the **Identity Provider** dropdown, select **Keycloak**. +4. Save the changes. + +!!! info "Notice" + + The existing SQL password is **not overwritten**. If you switch the authentication source back to **mailcow**, the user will be able to log in with their previous password. + +--- + +### **Authentication for External Mail Clients (IMAP, SIEVE, POP3, SMTP)** +!!! info "Notice" + + This does not necessarily apply to users utilizing the Mailpassword Flow. + +Before users can use external mail clients, they must first log in to the mailcow UI and navigate to the **Mailbox Settings**. +In the **App Passwords** tab, they can generate a new app password, which must then be used for authentication in the external mail client. + +--- + +### **Troubleshooting** + +If users cannot log in, first check the log details under: `System > Information > Logs > mailcow UI`. +Then, follow these steps to diagnose and resolve the issue: + +1. **Test Connection** + - Navigate to **`System > Configuration > Access > Identity Provider`**. + - Run the **Connection Test** and ensure it completes successfully. + +2. **Verify the User’s Mail Domain** + - Ensure the user’s mail domain exists in mailcow. + - Check if the domain is limited by **"Max. possible mailboxes"** or **"Domain quota"**. + +3. **Confirm Attribute Mapping** + - Make sure a matching **Attribute Mapping** is configured for the users. + +If you’re experiencing issues with **`Periodic Full Sync`** or **`Import Users`**, review the logs under `System > Information > Logs > Crontasks` diff --git a/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.de.md b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.de.md new file mode 100644 index 000000000..7754b17aa --- /dev/null +++ b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.de.md @@ -0,0 +1,88 @@ +### **Konfigurieren** + +Um einen **Identity Provider** zu konfigurieren, melden Sie sich als Administrator in der *mailcow UI* an, navigieren Sie zu +`System > Konfiguration > Zugriff > Identity Provider` und wählen Sie **LDAP** aus dem Dropdown-Menü aus. + +* `Host`: Die Adresse Ihres LDAP-Servers. Sie können entweder eine einzelne Hostadresse oder eine durch Kommas getrennte Liste von Hosts angeben, die als Fallbacks verwendet werden können. +* `Port`: Der Port, über den die Verbindung zum LDAP-Server hergestellt wird. +* `Benutze SSL`: Aktiviert eine LDAPS-Verbindung. Wenn der Port auf `389` gesetzt ist, wird er automatisch auf `636` geändert. +* `Benutze TLS`: Aktiviert eine TLS-Verbindung. **TLS wird gegenüber SSL empfohlen**. SSL-Ports können nicht verwendet werden. +* `Ignoriere SSL Fehler`: Wenn aktiviert, wird die Überprüfung des SSL-Zertifikats deaktiviert. +* `Base DN`: Der Distinguished Name (DN), von dem aus Suchanfragen durchgeführt werden. +* `Username Feld`: Das LDAP-Attribut, das zur Identifizierung von Benutzern bei der Authentifizierung verwendet wird. Standardwert: `mail`. +* `Filter`: Ein optionaler LDAP-Suchfilter, um einzuschränken, welche Benutzer sich authentifizieren können. +* `Attribut Feld`: Gibt ein LDAP-Attribut an, dessen Wert einer Mailbox-Vorlage über die **Attribut Mapping** zugeordnet werden kann. +* `Bind DN`: Der Distinguished Name (DN) des LDAP-Benutzers, der für die Authentifizierung und LDAP-Suchanfragen verwendet wird. Dieses Konto sollte ausreichende Berechtigungen zum Lesen der erforderlichen Attribute haben. +* `Bind-Passwort`: Das Passwort für den **Bind DN**-Benutzer. Es wird für die Authentifizierung beim Herstellen einer Verbindung mit dem LDAP-Server benötigt. +* `Attribut Mapping`: + * `Attribut`: Definiert den LDAP-Attributwert, der zugeordnet werden soll. + * `Vorlage`: Gibt an, welche Mailbox-Vorlage für den definierten LDAP-Attributwert angewendet werden soll. +* `Vollsynchronisation`: Wenn aktiviert, wird regelmäßig eine vollständige Synchronisation aller LDAP-Benutzer durchgeführt. +* `Importiere Benutzer`: Wenn aktiviert, werden neue Benutzer automatisch aus LDAP in mailcow importiert. +* `Sync / Import interval (min)`: Definiert das Zeitintervall (in Minuten) für den "Vollsynchronisation" und den "Importiere Benutzer". + +--- + +### **Automatische Benutzerbereitstellung** + +Wenn ein Benutzer in **mailcow** ^^nicht^^ existiert und sich über **Mail-Protokolle** (IMAP, SIEVE, POP3, SMTP) oder die **mailcow UI** anmeldet, wird er **automatisch erstellt**, sofern ein passendes **Attribut Mapping** konfiguriert ist. + +#### **Funktionsweise** +1. Bei der Anmeldung führt **mailcow** einen **LDAP-Bind** durch und ruft bei Erfolg die LDAP-Attribute des Benutzers ab. +2. **mailcow** sucht nach dem angegebenen **`Attribut Feld`** und ruft dessen Wert ab. +3. Wenn der Wert mit einem Attribut in der **Attribut Mapping** übereinstimmt, wird die entsprechende **Mailbox-Vorlage** angewendet. + +#### **Beispielkonfiguration** +- Der Benutzer hat das LDAP-Attribut **`otherMailbox`** mit dem Wert **`default`**. +- In **mailcow** wird das **`Attribut Feld`** auf **`othermailbox`** gesetzt. +- Unter **Attribut Mapping** wird das **`Attribut`** auf **`default`** gesetzt und eine geeignete Mailbox-Vorlage ausgewählt. + +#### **Updates bei der Anmeldung** +Jedes Mal, wenn sich ein Benutzer anmeldet, überprüft **mailcow**, ob sich die zugewiesene Vorlage geändert hat. Falls ja, werden die Mailbox-Einstellungen entsprechend aktualisiert. + +#### **Import und Updates über Crontasks** + +Wenn die Option **Benutzer importieren** aktiviert ist, wird ein geplanter Cron-Job ausgeführt, der Benutzer aus dem LDAP in mailcow importiert. Dies erfolgt in dem festgelegten **Sync / Import interval (min)**. + +Wenn die Option **Vollsynchronisation** aktiviert ist, aktualisiert der Cron-Job auch **bestehende Benutzer** im festgelegten **Sync / Import interval (min)** und übernimmt Änderungen aus LDAP in mailcow. + +Logs zu Importen und Synchronisationen können unter `System > Information > Logs > Crontasks` eingesehen werden. + +--- + +### **Authentifizierungsquelle für bestehende Benutzer ändern** + +Nachdem ein **LDAP Identity Provider** konfiguriert wurde, kann die Authentifizierungsquelle bestehender Benutzer von **mailcow** auf **LDAP** umgestellt werden. + +1. Navigieren Sie zu **`E-Mail > Konfiguration > Mailboxen`**. +2. Bearbeiten Sie den Benutzer. +3. Wählen Sie im **Identity Provider**-Dropdown **LDAP** aus. +4. Speichern Sie die Änderungen. + +!!! info "Hinweis" + + Das bestehende SQL-Passwort wird **nicht überschrieben**. Falls die Authentifizierungsquelle wieder auf **mailcow** umgestellt wird, kann der Benutzer sich wieder mit seinem vorherigen Passwort anmelden. + +--- + +### **Fehlersuche** + +Wenn Benutzer sich nicht anmelden können, überprüfen Sie zuerst die Logs unter: `System > Information > Logs > mailcow UI`. +Danach können Sie diesen Schritten zur Fehlerbehebung folgen: + +1. **Verbindung testen** + - Gehen Sie zu **`System > Konfiguration > Zugriff > Identity Provider`**. + - Klicken Sie den **Verbindung Testen** Button und stellen Sie sicher, dass er erfolgreich abgeschlossen wird. + +2. **Mail Domain des Benutzers prüfen** + - Stellen Sie sicher, dass die Domain des Benutzers in mailcow existiert. + - Überprüfen Sie, ob die Domain durch **"Max. Mailboxanzahl"** oder **"Domain Speicherplatz gesamt (MiB)"** eingeschränkt ist. + +3. **Attribut Mapping prüfen** + - Stellen Sie sicher, dass eine passendes **Attribut Mapping** für die Benutzer konfiguriert ist. + +4. **LDAP-Filter prüfen** + - Falls ein **LDAP-Filter** konfiguriert wurde, stellen Sie sicher, dass er die richtigen Benutzer einschließt. + +Falls Probleme mit den Optionen **`Vollsynchronisation`** oder **`Benutzer importieren`** auftreten, überprüfen Sie die Logs unter: +`System > Information > Logs > Crontasks`. diff --git a/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.en.md b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.en.md new file mode 100644 index 000000000..9c98bc144 --- /dev/null +++ b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.en.md @@ -0,0 +1,84 @@ +### **Configure** + +To add or edit your **Identity Provider** configuration, log in to your *mailcow UI* as administrator, go to `System > Configuration > Access > Identity Provider` and select **LDAP** from the Identity Provider dropdown. + +* `Host`: The address of your LDAP server. You can provide a single hostname or a comma-separated list of hosts for fallback in case the primary server is unreachable. +* `Port`: The port used to connect to the LDAP server. +* `Use SSL`: enable LDAPS connection. If Port is set to `389` it will be overriden to `636`. +* `Use TLS`: enable TLS connection. **TLS is recommended over SSL**. SSL Ports cannot be used. +* `Ignore SSL Errors`: If enabled, SSL certificate validation will be bypassed. +* `Base DN`: The Distinguished Name (DN) from which searches will be performed. +* `Username Field`: The LDAP attribute used to identify users during authentication. Defaults to `mail`. +* `Filter`: An optional LDAP search filter to refine which users can authenticate. +* `Attribute Field`: Specifies an LDAP attribute that holds a specific value which can be mapped to a mailbox template using the **Attribute Mapping** section. +* `Bind DN`: The Distinguished Name (DN) of the LDAP user that will be used to authenticate and perform LDAP searches. This account should have sufficient permissions to read the required attributes. +* `Bind Password`: The password for the **Bind DN** user. It is required for authentication when connecting to the LDAP server. +* `Attribute Mapping`: + * `Attribute`: Defines the LDAP attribute value that should be mapped. + * `Template`: Specifies which mailbox template should be applied for the defined LDAP attribute value +* `Periodic Full Sync`: If enabled, a full synchronization of all LDAP users and attributes will be performed periodically. +* `Import Users`: If enabled, new users will be automatically imported from LDAP into mailcow. +* `Sync / Import Interval (min)`: Defines the time interval (in minutes) for periodic synchronization and user imports. + +--- + +### **Automatic User Provisioning** +If a user does not exist in **mailcow** and logs in via **mail protocols** (IMAP/SIEVE/POP3/SMTP) or the **mailcow UI**, the user will be **automatically created**, provided that a matching **attribute mapping** is configured. + +#### **How It Works** +1. On login, **mailcow** performs an **LDAP bind** and, if successful, retrieves the user's LDAP attributes. +2. **mailcow** looks for the specified **`Attribute Field`** and retrieves its value. +3. If the value matches an attribute defined in the **Attribute Mapping**, the corresponding **mailbox template** is applied. + +#### **Example Configuration** +- The user has an LDAP attribute **`otherMailbox`** with the value **`default`**. +- In **mailcow**, set **`Attribute Field`** to **`othermailbox`**. +- Under **Attribute Mapping**, set **`Attribute`** to **`default`** and select an appropriate mailbox template. + +#### **Updates on Login** +Each time a user logs in, **mailcow** checks if the assigned template has changed. If so, it updates the mailbox settings accordingly. + +#### **Import and Updates via Crontask** +If **Import Users** is enabled, a scheduled cron job will automatically import users from LDAP to mailcow at the specified **Sync / Import Interval (min)**. + +If **Periodic Full Sync** is enabled, the cron job will also update existing users at the specified **Sync / Import Interval (min)**, ensuring that any changes in LDAP are applied to their corresponding mailboxes in mailcow. + +Check the logs for imports and sync updates under `System > Information > Logs > Crontasks`. + +--- + +### **Change the Authentication Source for Existing Users** + +Once you have configured an **LDAP Identity Provider**, you can change the authentication source for existing users from **mailcow** to **LDAP**. + +1. Navigate to **`E-Mail > Configuration > Mailboxes`**. +2. Edit the user. +3. From the **Identity Provider** dropdown, select **LDAP**. +4. Save the changes. + +!!! info "Notice" + + The existing SQL password is **not overwritten**. If you switch the authentication source back to **mailcow**, the user will be able to log in with their previous password. + +--- + +### **Troubleshooting** + +If users cannot log in, first check the log details under: `System > Information > Logs > mailcow UI`. +Then, follow these steps to diagnose and resolve the issue: + +1. **Test Connection** + - Navigate to **`System > Configuration > Access > Identity Provider`**. + - Run the **Connection Test** and ensure it completes successfully. + +2. **Verify the User’s Mail Domain** + - Ensure the user’s mail domain exists in mailcow. + - Check if the domain is limited by **"Max. possible mailboxes"** or **"Domain quota"**. + +3. **Confirm Attribute Mapping** + - Make sure a matching **Attribute Mapping** is configured for the users. + +4. **LDAP Filter** + - Double-check your LDAP filter if one is configured. + +If you’re experiencing issues with **`Periodic Full Sync`** or **`Import Users`**, review the logs under `System > Information > Logs > Crontasks` diff --git a/mkdocs.yml b/mkdocs.yml index 9eb88f093..8e93ca707 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,7 +18,7 @@ theme: name: Switch to light mode # Palette toggle for light mode - media: "(prefers-color-scheme: light)" - scheme: default + scheme: default toggle: icon: material/brightness-7 name: Switch to dark mode @@ -29,7 +29,7 @@ theme: toggle: icon: material/brightness-4 name: Switch to system preference - + logo: assets/images/logo.svg favicon: assets/images/favicon.png features: @@ -97,7 +97,7 @@ nav: - 'IP bindings': 'post_installation/firststeps-ip_bindings.md' - 'Local MTA on Docker host': 'post_installation/firststeps-local_mta.md' - 'Logging': 'post_installation/firststeps-logging.md' - - 'Reverse Proxy': + - 'Reverse Proxy': - 'Overview': 'post_installation/reverse-proxy/r_p.md' - 'Apache 2.4': 'post_installation/reverse-proxy/r_p-apache24.md' - 'Nginx': 'post_installation/reverse-proxy/r_p-nginx.md' @@ -138,6 +138,9 @@ nav: - 'Temporary email aliases': 'manual-guides/mailcow-UI/u_e-mailcow_ui-spamalias.md' - 'Two-Factor Authentication': 'manual-guides/mailcow-UI/u_e-mailcow_ui-tfa.md' - 'WebAuthn / FIDO2': 'manual-guides/mailcow-UI/u_e-mailcow_ui-fido.md' + - 'LDAP': 'manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.md' + - 'Keycloak': 'manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.md' + - 'Generic-OIDC': 'manual-guides/mailcow-UI/u_e-mailcow_ui-generic-oidc.md' - 'Postfix': - 'Unauthenticated Relaying': 'manual-guides/Postfix/u_e-postfix-unauthenticated-relaying.md' - 'Custom transport maps': 'manual-guides/Postfix/u_e-postfix-custom_transport.md' @@ -210,7 +213,7 @@ nav: - 'Portainer': 'third_party/portainer/third_party-portainer.md' - 'Roundcube': 'third_party/roundcube/third_party-roundcube.md' -plugins: +plugins: - i18n: # <--- Translation plugin docs_structure: suffix fallback_to_default: true