Merge pull request #825 from mailcow/ldap-oidc
Add LDAP and OIDC documentation
This commit is contained in:
FreddleSpl0it
GitHub
commit
7ed0ae1728
7 changed files with 575 additions and 4 deletions
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
123
docs/manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.de.md
Normal file
123
docs/manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.de.md
Normal file
|
|
@ -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`.
|
||||
120
docs/manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.en.md
Normal file
120
docs/manual-guides/mailcow-UI/u_e-mailcow_ui-keycloak.en.md
Normal file
|
|
@ -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`
|
||||
88
docs/manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.de.md
Normal file
88
docs/manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.de.md
Normal file
|
|
@ -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`.
|
||||
84
docs/manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.en.md
Normal file
84
docs/manual-guides/mailcow-UI/u_e-mailcow_ui-ldap.en.md
Normal file
|
|
@ -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`
|
||||
11
mkdocs.yml
11
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue