Update LDAP and OIDC documentation
This commit is contained in:
FreddleSpl0it
parent
37173286f1
commit
264c096ea6
6 changed files with 76 additions and 40 deletions
|
|
@ -13,25 +13,25 @@ Um einen **Identity Provider** zu konfigurieren, melde Sie sich als Administrato
|
|||
* `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 Errors`: Wenn aktiviert, wird die Überprüfung des SSL-Zertifikats deaktiviert.
|
||||
* `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 eine passende **Attribut Mapping** konfiguriert ist.
|
||||
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 der **Attribut Mapping** übereinstimmt, wird die entsprechende **Mailbox-Vorlage** angewendet.
|
||||
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 **Vorlage** geändert hat. Falls ja, werden die Mailbox-Einstellungen entsprechend aktualisiert.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -44,17 +44,22 @@ Nachdem ein **Generic-OIDC Identity Provider** konfiguriert wurde, kann die Auth
|
|||
3. Wählen Sie im **Identity Provider**-Dropdown **Generic-OIDC** aus.
|
||||
4. Speichern Sie die Änderungen.
|
||||
|
||||
!!! note "Hinweis"
|
||||
!!! 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`.
|
||||
|
||||
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**
|
||||
|
|
@ -62,7 +67,7 @@ Danach können Sie diesen Schritten zur Fehlerbehebung folgen:
|
|||
- Klicken Sie den **Verbindung Testen** Button und stellen Sie sicher, dass er erfolgreich abgeschlossen wird.
|
||||
|
||||
2. **Client-Daten überprüfen**
|
||||
- Gehe zu `System > Konfiguration > Zugriff > Identity Provider`.
|
||||
- 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**
|
||||
|
|
@ -71,6 +76,3 @@ Danach können Sie diesen Schritten zur Fehlerbehebung folgen:
|
|||
|
||||
3. **Attribut Mapping prüfen**
|
||||
- Stellen Sie sicher, dass eine passendes **Attribut Mapping** für die Benutzer konfiguriert ist.
|
||||
|
||||
Falls Probleme mit `Periodic Full Sync` oder `Import Users` auftreten, überprüfen Sie die Logs unter:
|
||||
`System > Information > Logs > Crontasks`.
|
||||
|
|
|
|||
|
|
@ -42,12 +42,19 @@ Once you have configured an **Generic-OIDC Identity Provider**, you can change t
|
|||
3. From the **Identity Provider** dropdown, select **Generic-OIDC**.
|
||||
4. Save the changes.
|
||||
|
||||
!!! note "Notice"
|
||||
!!! 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:
|
||||
|
|
@ -66,5 +73,3 @@ If users are unable to log in, follow these steps to diagnose and resolve the is
|
|||
|
||||
4. **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`
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
### **Konfigurieren**
|
||||
|
||||
Um einen **Identity Provider** zu konfigurieren, melde Sie sich als Administrator in der *mailcow UI* an, navigieren Sie zu
|
||||
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.
|
||||
|
|
@ -15,10 +15,10 @@ Um einen **Identity Provider** zu konfigurieren, melde Sie sich als Administrato
|
|||
* `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 Errors`: Wenn aktiviert, wird die Überprüfung des SSL-Zertifikats deaktiviert.
|
||||
* `Periodic Full Sync`: Wenn aktiviert, synchronisiert mailcow regelmäßig alle Benutzer aus Keycloak.
|
||||
* `Import Users`: Wenn aktiviert, werden neue Benutzer automatisch aus Keycloak in mailcow importiert.
|
||||
* `Sync / Import interval (min)`: Definiert das Zeitintervall (in Minuten) für den "Periodic Full Sync" und den "Import Users".
|
||||
* `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".
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -36,7 +36,7 @@ Wenn ein Benutzer in **mailcow** nicht existiert und sich über die **mailcow UI
|
|||
- 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 **Vorlage** geändert hat. Falls ja, werden die Mailbox-Einstellungen entsprechend aktualisiert.
|
||||
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"
|
||||
|
|
@ -44,9 +44,9 @@ Jedes Mal, wenn sich ein Benutzer über die **mailcow UI** anmeldet, überprüft
|
|||
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 **Import Users** 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 **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 **Periodic Full Sync** aktiviert ist, aktualisiert der Cron-Job auch bestehende Benutzer im festgelegten **Sync / Import interval (min)** und übernimmt Änderungen aus Keycloak in mailcow.
|
||||
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.
|
||||
|
||||
|
|
@ -65,9 +65,16 @@ Mit dem **Mailpassword Flow** funktioniert die automatische Benutzerbereitstellu
|
|||
#### **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** enthalten, das zur Authentifizierung verwendet wird.
|
||||
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 UI und Mail-Protokolle.
|
||||
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}/'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -80,12 +87,22 @@ Nachdem ein **Keycloak Identity Provider** konfiguriert wurde, kann die Authenti
|
|||
3. Wählen Sie im **Identity Provider**-Dropdown **Keycloak** aus.
|
||||
4. Speichern Sie die Änderungen.
|
||||
|
||||
!!! note "Hinweis"
|
||||
!!! 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`.
|
||||
|
|
@ -102,5 +119,5 @@ Danach können Sie diesen Schritten zur Fehlerbehebung folgen:
|
|||
3. **Attribut Mapping prüfen**
|
||||
- Stellen Sie sicher, dass eine passendes **Attribut Mapping** für die Benutzer konfiguriert ist.
|
||||
|
||||
Falls Probleme mit **`Periodic Full Sync`** oder **`Import Users`** auftreten, überprüfen Sie die Logs unter:
|
||||
Falls Probleme mit **`Vollsynchronisation`** oder **`Importiere Benutzer`** auftreten, überprüfen Sie die Logs unter:
|
||||
`System > Information > Logs > Crontasks`.
|
||||
|
|
|
|||
|
|
@ -63,10 +63,17 @@ With the **Mailpassword Flow**, automatic user provisioning also works for login
|
|||
#### **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**, which will be used for verification.
|
||||
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**
|
||||
|
|
@ -78,12 +85,22 @@ Once you have configured an **Keycloak Identity Provider**, you can change the a
|
|||
3. From the **Identity Provider** dropdown, select **Keycloak**.
|
||||
4. Save the changes.
|
||||
|
||||
!!! note "Notice"
|
||||
!!! 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`.
|
||||
|
|
|
|||
|
|
@ -17,9 +17,9 @@ Um einen **Identity Provider** zu konfigurieren, melden Sie sich als Administrat
|
|||
* `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.
|
||||
* `Periodic Full Sync`: Wenn aktiviert, wird regelmäßig eine vollständige Synchronisation aller LDAP-Benutzer durchgeführt.
|
||||
* `Import Users`: Wenn aktiviert, werden neue Benutzer automatisch aus LDAP in mailcow importiert.
|
||||
* `Sync / Import interval (min)`: Definiert das Zeitintervall (in Minuten) für den "Periodic Full Sync" und den "Import Users".
|
||||
* `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".
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -34,14 +34,9 @@ Wenn ein Benutzer in **mailcow** ^^nicht^^ existiert und sich über **Mail-Proto
|
|||
|
||||
#### **Beispielkonfiguration**
|
||||
- Der Benutzer hat das LDAP-Attribut **`otherMailbox`** mit dem Wert **`default`**.
|
||||
- In **mailcow** wird das **`Attribut Feld`** auf **`otherMailbox`** gesetzt.
|
||||
- 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.
|
||||
|
||||
!!! info "Hinweis"
|
||||
Der Attribut Wert (in dem Fall `default`) muss von mailcow auf eine Mailbox Vorlage gemappt werden, damit neue Mailboxen mit dieser Vorlage erstellt werden.
|
||||
|
||||
Es sind mehrere Mappings möglich.
|
||||
|
||||
#### **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.
|
||||
|
||||
|
|
@ -64,7 +59,7 @@ Nachdem ein **LDAP Identity Provider** konfiguriert wurde, kann die Authentifizi
|
|||
3. Wählen Sie im **Identity Provider**-Dropdown **LDAP** aus.
|
||||
4. Speichern Sie die Änderungen.
|
||||
|
||||
!!! note "Hinweis"
|
||||
!!! 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ Once you have configured an **LDAP Identity Provider**, you can change the authe
|
|||
3. From the **Identity Provider** dropdown, select **LDAP**.
|
||||
4. Save the changes.
|
||||
|
||||
!!! note "Notice"
|
||||
!!! 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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue