Added manual Guides (mailcow UI Section) + German Translation

Dieser Commit ist enthalten in:
Niklas Meyer 2022-01-31 11:08:49 +01:00
Ursprung b931593386
Commit 442d9dc6af
25 geänderte Dateien mit 478 neuen und 9 gelöschten Zeilen

Binäre Datei nicht angezeigt.

Vorher

Breite:  |  Höhe:  |  Größe: 12 KiB

Binäre Datei nicht angezeigt.

Nachher

Breite:  |  Höhe:  |  Größe: 70 KiB

Binäre Datei nicht angezeigt.

Nachher

Breite:  |  Höhe:  |  Größe: 55 KiB

Datei anzeigen

Vorher

Breite:  |  Höhe:  |  Größe: 40 KiB

Nachher

Breite:  |  Höhe:  |  Größe: 40 KiB

Datei anzeigen

Vorher

Breite:  |  Höhe:  |  Größe: 32 KiB

Nachher

Breite:  |  Höhe:  |  Größe: 32 KiB

Datei anzeigen

Vorher

Breite:  |  Höhe:  |  Größe: 24 KiB

Nachher

Breite:  |  Höhe:  |  Größe: 24 KiB

Datei anzeigen

@ -0,0 +1,11 @@
Um einen Eintrag zu Ihrer **domänenweiten** Filtertabelle hinzuzufügen oder zu bearbeiten, loggen Sie sich als (Domain-)Administrator in Ihre *mailcow UI* ein und wechseln Sie zu:
`Konfiguration > E-Mail Setup > Domains > Domain bearbeiten > Spam Filter`.
![Black- und Whitelist Konfiguration](../assets/images/manual-guides/mailcow-bl_wl.de.png)
!!! info
Seien Sie sich bewusst, dass ein Benutzer diese [Einstellung](u_e-mailcow_ui-spamfilter.de.md) ĂĽberschreiben kann, indem er seine eigene Black- und Whitelist setzt!
Es gibt auch eine globale Filtertabelle in `Konfiguration > Server Konfiguratiomn > Globale Filter-Maps`, um einen **serverweiten Filter** fĂĽr mehrere Regex-Maps zu konfigurieren (Todo: Screenshots).

Datei anzeigen

@ -0,0 +1,10 @@
To add or edit an entry to your **domain-wide** filter table, log in to your *mailcow UI* as (domain) administrator and go to:
`Configuration > Email Setup > Domains > Edit Domain > Spam Filter`.
![Black- and Whitelist Configuration](../assets/images/manual-guides/mailcow-bl_wl.en.png)
!!! info
Be aware that a user can override this [setting](u_e-mailcow_ui-spamfilter.en.md) by setting their own blacklist and whitelist!
There is also a global filter table in `Configuration > Configuration & Details > Global filter maps` to configure a **server wide** filter for multiple regex maps (todo: screenshots).

Datei anzeigen

@ -0,0 +1,19 @@
Mehrere Konfigurationsparameter der mailcow-Benutzeroberfläche können geändert werden, indem eine Datei `data/web/inc/vars.local.inc.php` erstellt wird, die die Standardeinstellungen in `data/web/inc/vars.inc.php` überschreibt.
Die lokale Konfigurationsdatei ist über Updates von mailcow hinweg beständig. Versuchen Sie nicht, die Werte in `data/web/inc/vars.inc.php` zu ändern, sondern verwenden Sie diese als Vorlage für die lokale Überschreibung.
mailcow UI Konfigurationsparameter können verwendet werden, um...
- ...die Standardsprache zu ändern[^1]
- ...das Standard-Bootstrap-Theme zu ändern
- ...eine Passwort-Komplexitäts-Regex zu setzen
- ...die Sichtbarkeit des privaten DKIM-SchlĂĽssels aktivieren
- ...eine Größe für den Paginierungsauslöser festlegen
- ...Standard-Postfach-Attribute festlegen
- ...Sitzungs-Lebensdauern ändern
- ...feste App-Menüs erstellen (die nicht in der mailcow UI geändert werden können)
- ...ein Standard "To"-Feld fĂĽr Relayhost-Tests einstellen
- ...ein Timeout fĂĽr Docker API Anfragen setzen
- ...IP-Anonymisierung umschalten
[^1]: Um SOGos Standardsprache zu ändern, müssen Sie `data/conf/sogo/sogo.conf` bearbeiten und "English" durch Ihre bevorzugte Sprache ersetzen.

Datei anzeigen

@ -0,0 +1,19 @@
Several configuration parameters of the mailcow UI can be changed by creating a file `data/web/inc/vars.local.inc.php` which overrides defaults settings found in `data/web/inc/vars.inc.php`.
The local configuration file is persistent over updates of mailcow. Try not to change values inside `data/web/inc/vars.inc.php`, but use them as template for the local override.
mailcow UI configuration parameters can be used to...
- ...change the default language[^1]
- ...change the default bootstrap theme
- ...set a password complexity regex
- ...enable DKIM private key visibility
- ...set a pagination trigger size
- ...set default mailbox attributes
- ...change session lifetimes
- ...create fixed app menus (which cannot be changed in mailcow UI)
- ...set a default "To" field for relayhost tests
- ...set a timeout for Docker API requests
- ...toggle IP anonymization
[^1]: To change SOGos default language, you will need to edit `data/conf/sogo/sogo.conf` and replace "English" by your preferred language.

Datei anzeigen

@ -0,0 +1,3 @@
FĂĽr benutzerdefinierte Ăśberschreibungen bestimmter Elemente ĂĽber CSS, verwenden Sie die `data/web/css/build/0081-custom-mailcow.css` Datei.
Die Datei wird von der Verfolgung (via Git) ausgeschlossen und bleibt bei Aktualisierungen erhalten.

Datei anzeigen

@ -0,0 +1,3 @@
For custom overrides of specific elements via CSS, use `data/web/css/build/0081-custom-mailcow.css`.
The file is excluded from tracking and persists over updates.

Datei anzeigen

@ -0,0 +1,18 @@
## Wie wird UV in mailcow gehandhabt?
Das UV-Flag (wie in "user verification") erzwingt, dass WebAuthn den Benutzer verifiziert, bevor es den Zugriff auf den Schlüssel erlaubt (denken Sie an eine PIN). Wir erzwingen keine UV, um Logins über iOS und NFC (YubiKey) zu ermöglichen.
## Login und SchlĂĽssel-Verarbeitung
mailcow verwendet **Client-seitige SchlĂĽsselverarbeitung**. Wir bitten den Authentifikator (d.h. YubiKey), die Registrierung in seinem Speicher zu speichern.
Ein Benutzer muss keinen Benutzernamen eingeben. Die verfügbaren Anmeldedaten - falls vorhanden - werden dem Nutzer angezeigt, wenn er den "Schlüssel-Login" über das Mailcow UI Login auswählt.
Beim Aufruf des Login-Prozesses werden dem Authentifikator keine Credential-IDs ĂĽbergeben. Dies wird ihn dazu zwingen, die Anmeldeinformationen in seinem eigenen Speicher zu suchen.
## Wer kann WebAuthn benutzen, um sich bei mailcow anzumelden?
Ab heute sind nur Administratoren und Domain-Administratoren in der Lage, WebAuthn/FIDO2 einzurichten.
---
**Sie wollen WebAuthn/Fido als 2FA verwenden? Schauen Sie sich das hier an: [Zwei-Faktoren-Authentifizierung](u_e-mailcow_ui-tfa.de.md)**

Datei anzeigen

@ -0,0 +1,18 @@
## How is UV handled in mailcow?
The UV flag (as in "user verification") enforces WebAuthn to verify the user before it allows access to the key (think of a PIN). We don't enforce UV to allow logins via iOS and NFC (YubiKey).
## Login and key processing
mailcow uses **client-side key processing**. We ask the authenticator (i.e. YubiKey) to save the registration in its memory.
A user does not need to enter a username. The available credentials - if any - will be shown to the user when selecting the "key login" via mailcow UI login.
When calling the login process, the authenticator is not given any credential IDs. This will force it to lookup credentials in its own memory.
## Who can use WebAuthn to login to mailcow?
As of today, only administrators and domain administrators are able to setup WebAuthn/FIDO2.
---
**You want to use WebAuthn/Fido as 2FA? Check it out here: [Two-Factor Authentication](u_e-mailcow_ui-tfa.en.md)**

Datei anzeigen

@ -0,0 +1,19 @@
!!! info
Pushover macht es einfach, Echtzeit-Benachrichtigungen auf Ihrem Android, iPhone, iPad und Desktop zu erhalten
Sie können Pushover verwenden, um eine Push-Benachrichtigung über jede E-Mail zu erhalten, die Sie für jede Mailbox erhalten, in der Sie diese Funktion aktiviert haben.
1\. Ă–ffnen Sie als Administrator die Einstellungen Ihres Postfachs und scrollen Sie nach unten zu den Pushover-Einstellungen
2\. Registrieren Sie sich bei [Pushover](https://pushover.net)
3\. Geben Sie Ihren "BenutzerschlĂĽssel" in das Feld "Benutzer-/GruppenschlĂĽssel" in den Einstellungen Ihres Postfachs ein
4\. Erstellen Sie eine Anwendung, um das API-Token/den API-SchlĂĽssel zu erhalten, das/den Sie ebenfalls in Ihre Postfacheinstellungen eintragen mĂĽssen.
5\. Optional können Sie den Titel/Text der Benachrichtigung bearbeiten und bestimmte Absender-E-Mail-Adressen festlegen, bei denen eine Push-Benachrichtigung ausgelöst wird
6\. Speichern Sie alles und ĂĽberprĂĽfen Sie dann Ihre Anmeldedaten.
Wenn alles erledigt ist, können Sie testen, ob Sie eine E-Mail senden können, und Sie erhalten eine Push-Nachricht auf Ihrem Telefon

Datei anzeigen

@ -0,0 +1,25 @@
!!! info
Pushover makes it easy to get real-time notifications on your Android, iPhone, iPad, and Desktop
You can use Pushover to get a push notification on every mail you receive for each mailbox where you enabled this feature.
1\. As admin open your mailbox' settings and scroll down to the Pushover settings
2\. Register yourself on [Pushover](https://pushover.net)
3\. Put your 'User Key' in the 'User/Group Key' field in your mailbox settings
4\. Create an Applications to get the API Token/Key which you also need to put in your mailbox settings
5\. Optional you can edit the notification title/text and define certain sender email addresses where a push notification is triggered
6\. Save everything and then you can verify your credentials
If everything is done you can test sending a mail and you will receive a push message on your phone

Datei anzeigen

@ -0,0 +1,5 @@
Diese temporären E-Mail-Aliasnamen werden meist dort verwendet, wo wir eine E-Mail-Adresse angeben müssen, aber keine weitere E-Mails wünschen. Sie werden auch Spam-Alias genannt.
Um ein temporäres E-Mail-Alias zu erstellen, zu löschen oder zu erweitern, müssen Sie sich in mailcow's UI als Mailbox-Nutzer anmelden und zum Reiter **Temporäre E-Mail-Aliase** navigieren:
![Wie man Spam- oder temporäre E-Mail-Aliase in mailcow einrichtet](..images/manual-guides/mailcow-spamalias.de.png)

Datei anzeigen

@ -0,0 +1,5 @@
These temporary email aliases are mostly used for places where we need to provide an email address but don't want future correspondence with. They are also called spam alias.
To create, delete or extend a temporary email aliases you need to login to mailcow's UI as a mailbox user and navigate to the tab **Temporary email aliases**:
![How to set spam- or temporary email aliases in mailcow](..images/manual-guides/mailcow-spamalias.en.png)

Datei anzeigen

@ -0,0 +1,7 @@
Ein Mailbox-Nutzer kann den Spam-Filter und die Black-/Whitelist-Einstellungen für seine Mailbox individuell anpassen, indem er zum Reiter **Spam-Filter** in der Mailcow-Benutzeroberfläche navigiert.
![Wo man die Spam-, Black- und Whitelist-Einstellungen des Benutzers anpasst](../images/manual-guides/mailcow-spamfilter.de.png)
!!! info
FĂĽr globale Einstellungen Ihres Spamfilters lesen Sie bitte unseren Abschnitt ĂĽber [Rspamd](../Rspamd/u_e-rspamd.de.md).
FĂĽr eine domainweite Black- und Whitelist lesen Sie bitte unsere Anleitung zu [Black / Whitelist](u_e-mailcow_ui-bl_wl.de.md)

Datei anzeigen

@ -0,0 +1,7 @@
A mailbox user may adjust the spam filter and black- / whitelist settings for his mailbox individually by navigating to the **Spam filter** tab in the users mailcow UI.
![Where to adjust the users spam, black- and whitelist settings](../images/manual-guides/mailcow-spamfilter.en.png)
!!! info
For global adjustments on your spam filter please check our section on [Rspamd](../Rspamd/u_e-rspamd.en.md).
For a domain wide black- and whitelist please check our guide on [Black / Whitelist](u_e-mailcow_ui-bl_wl.en.md)

Datei anzeigen

@ -0,0 +1,28 @@
Mailbox-Nutzer können ihre Mailadresse wie in "me+facebook@example.org" markieren. Sie können die Tag-Behandlung im **mailcow UI** Panel (für den Benutzer) unter `Mailbox > Einstellungen` kontrollieren.
![mailcow mail tagging settings](..images/manual-guides/mailcow-tagging.de.png)
*Tagging ist auch bekannt als 'Sub-Adressierung' (RFC 5233) oder 'Plus-Adressierung'*
### VerfĂĽgbare Aktionen
1\. Diese Nachricht in einen Unterordner "facebook" verschieben (wird in Kleinbuchstaben erstellt, falls nicht vorhanden)
2\. Den Tag dem Betreff voranstellen: "[facebook] Betreff"
Bitte beachten Sie: GroĂźgeschriebene Tags werden in Kleinbuchstaben umgewandelt, mit Ausnahme des ersten Buchstabens. Wenn Sie den Tag so lassen wollen, wie er ist, wenden Sie bitte den folgenden Diff an und starten Sie mailcow neu:
```
diff --git a/data/conf/dovecot/global_sieve_after b/data/conf/dovecot/global_sieve_after
index e047136e..933c4137 100644
--- a/data/conf/dovecot/global_sieve_after
+++ b/data/conf/dovecot/global_sieve_after
@@ -15,7 +15,7 @@ if allof (
envelope :detail :matches "to" "*",
header :contains "X-Moo-Tag" "YES"
) {
- set :lower :upperfirst "tag" "${1}";
+ set "tag" "${1}";
if mailboxexists "INBOX/${1}" {
fileinto "INBOX/${1}";
} else {
```

Datei anzeigen

@ -0,0 +1,28 @@
Mailbox users can tag their mail address like in `me+facebook@example.org`. They can control the tag handling in the users **mailcow UI** panel under `Mailbox > Settings`.
![mailcow mail tagging settings](..images/manual-guides/mailcow-tagging.en.png)
*Tagging is also known as 'sub-addressing' (RFC 5233) or 'plus addressing'*
### Available Actions
1\. Move this message to a sub folder "facebook" (will be created lower case if not existing)
2\. Prepend the tag to the subject: "[facebook] Subject"
Please note: Uppercase tags are converted to lowercase except for the first letter. If you want to keep the tag as it is, please apply the following diff and restart mailcow:
```
diff --git a/data/conf/dovecot/global_sieve_after b/data/conf/dovecot/global_sieve_after
index e047136e..933c4137 100644
--- a/data/conf/dovecot/global_sieve_after
+++ b/data/conf/dovecot/global_sieve_after
@@ -15,7 +15,7 @@ if allof (
envelope :detail :matches "to" "*",
header :contains "X-Moo-Tag" "YES"
) {
- set :lower :upperfirst "tag" "${1}";
+ set "tag" "${1}";
if mailboxexists "INBOX/${1}" {
fileinto "INBOX/${1}";
} else {
```

Datei anzeigen

@ -0,0 +1,121 @@
Bislang sind drei Methoden fĂĽr die _Zwei-Faktor-Authentifizierung_ implementiert: WebAuthn (ersetzt seit Februar 2022 U2F), Yubi OTP und TOTP
- Damit WebAuthn funktioniert, benötigen Sie eine verschlüsselte Verbindung zum Server (HTTPS) sowie einen FIDO-Sicherheitsschlüssel.
- Sowohl WebAuthn als auch Yubi OTP funktionieren gut mit dem fantastischen [Yubikey](https://www.yubico.com).
- Während Yubi OTP eine aktive Internetverbindung und eine API ID + Schlüssel benötigt, funktioniert WebAuthn mit jedem Fido Security Key, kann aber nur verwendet werden, wenn der Zugriff auf mailcow über HTTPS erfolgt.
- WebAuthn und Yubi OTP unterstĂĽtzen mehrere SchlĂĽssel pro Nutzer.
- Als dritte TFA-Methode verwendet mailcow TOTP: zeitbasierte Einmal-Passwörter. Diese Passwörter können mit Apps wie "Google Authenticator" generiert werden, nachdem zunächst ein QR-Code gescannt oder das gegebene Geheimnis manuell eingegeben wurde.
Als Administrator können Sie den TFA-Login eines Domain-Administrators vorübergehend deaktivieren, bis dieser sich erfolgreich eingeloggt hat.
Der für die Anmeldung verwendete Schlüssel wird in grüner Farbe angezeigt, während andere Schlüssel grau bleiben.
Informationen zum Entfernen von 2FA finden Sie [hier](../troubleshooting/debug-reset_pw.de.md#zwei-faktor-authentifizierung-entfernen).
## Yubi OTP
Die Yubi API ID und der Schlüssel werden mit der Yubico Cloud API abgeglichen. Bei der Einrichtung von TFA werden Sie nach Ihrem persönlichen API-Konto für diesen Schlüssel gefragt.
Die API-ID, der API-SchlĂĽssel und die ersten 12 Zeichen (Ihre YubiKeys ID in modhex) werden in der MySQL-Tabelle als Geheimnis gespeichert.
### Beispiel-Einrichtung
Als erstes muss der YubiKey fĂĽr die Verwendung als OTP-Generator konfiguriert werden. Laden Sie dazu den `YubiKey Manager` von der Yubico Website herunter: [hier](https://www.yubico.com/support/download/)
Im Folgenden konfigurieren Sie den YubiKey fĂĽr OTP.
Über den Menüpunkt `Anwendungen` -> `OTP` und einem Klick auf den `Konfigurieren` Button. Wählen Sie im folgenden Menü `Credential Type` -> `Yubico OTP` und klicken Sie auf `Next`.
Setzen Sie ein Häkchen in die Checkbox `Use serial`, generieren Sie eine `Private ID` und einen `Secret key` über die Schaltflächen.
Damit der YubiKey später validiert werden kann, muss auch das Häkchen in der `Upload` Checkbox gesetzt werden und klicken Sie dann auf `Finish`.
Nun öffnet sich ein neues Browserfenster, in dem Sie unten im Formular ein OTP Ihres YubiKey eingeben müssen (auf das Feld klicken und dann auf Ihren YubiKey tippen). Bestätigen Sie das Captcha und laden Sie die Daten auf den Yubico-Server hoch, indem Sie auf 'Hochladen' klicken. Die Verarbeitung der Daten wird einen Moment dauern.
Nachdem die Generierung erfolgreich war, werden Ihnen eine `Client ID` und ein `Secret key` angezeigt, notieren Sie sich diese Informationen an einem sicheren Ort.
Nun können Sie `Yubico OTP-Authentifizierung` aus dem Dropdown-Menü in der mailcow UI auf der Startseite unter `Zugang` -> `Zwei-Faktor-Authentifizierung` auswählen.
In dem sich nun öffnenden Dialog können Sie einen Namen für diesen YubiKey eingeben und die zuvor notierte `Client ID` sowie den `Secret key` in die vorgesehenen Felder eintragen.
Geben Sie schließlich Ihr aktuelles Kontopasswort ein und berühren Sie nach Auswahl des Feldes `Touch Yubikey` die Schaltfläche Ihres YubiKey.
Herzlichen Glückwunsch! Sie können sich nun mit Ihrem YubiKey in die mailcow UI einloggen!
---
## WebAuthn (U2F, Ersatz)
!!! warning
**Seit Februar 2022 hat Google Chrome die UnterstĂĽtzung fĂĽr U2F aufgegeben und die Verwendung von WebAuthn standardisiert.<br>**
*Die WebAuthn API (der Ersatz fĂĽr U2F) ist seit dem 21. Januar 2022 Teil von mailcow, wenn Sie also den Key ĂĽber Februar 2022 hinaus nutzen wollen, sollten Sie ein Update mit der `update.sh`* in Betracht ziehen.
Um WebAuthn zu nutzen, muss der Browser diesen Standard unterstĂĽtzen:
- Edge (>=18)
- Firefox (>=60)
- Chrome (>=67)
- Safari (>=13)
- Opera (>=54)
Die folgenden mobilen Browser unterstĂĽtzen diesen Authentifizierungstyp:
- Safari auf iOS (>=14.5)
- Android-Browser (>=97)
- Opera Mobil (>=64)
- Chrome fĂĽr Android (>=97)
Quellen: [caniuse.com](https://caniuse.com/webauthn), [blog.mozilla.org](https://blog.mozilla.org/security/2019/04/04/shipping-fido-u2f-api-support-in-firefox/)
WebAuthn funktioniert auch ohne Internetverbindung.
### Was passiert mit meinem registrierten Fido Security Key nach dem Update von U2F auf WebAuthn?
!!! warning
Mit dem neuen U2F-Ersatz (WebAuthn) müssen Sie Ihren Fido Security Key neu registrieren, zum Glück ist WebAuthn abwärtskompatibel und unterstützt das U2F-Protokoll.
Im Idealfall sollten Sie beim nächsten Einloggen (mit dem Schlüssel) ein Textfeld erhalten, das besagt, dass Ihr Fido Security Key aufgrund des Updates auf WebAuthn entfernt und als 2-Faktor-Authentifikator gelöscht wurde.
Aber keine Sorge! Sie können Ihren bestehenden Schlüssel einfach neu registrieren und ihn wie gewohnt verwenden. Sie werden wahrscheinlich nicht einmal einen Unterschied bemerken, außer dass Ihr Browser die U2F-Deaktivierungsmeldung nicht mehr anzeigt.
### Deaktivieren inoffizieller unterstĂĽtzter Fido Security Keys
Mit WebAuthn gibt es die Möglichkeit, nur offizielle Fido Security Keys zu verwenden (von den großen Marken wie: Yubico, Apple, Nitro, Google, Huawei, Microsoft, usw.) zu verwenden.
Dies dient in erster Linie der Sicherheit, da es Administratoren ermöglicht, sicherzustellen, dass nur offizielle Hardware in ihrer Umgebung verwendet werden kann.
Um diese Funktion zu aktivieren, ändern Sie den Wert `WEBAUTHN_ONLY_TRUSTED_VENDORS` in mailcow.conf von `n` auf `y` und starten Sie die betroffenen Container mit `docker-compose up -d` neu.
Die mailcow wird nun die Vendor-Zertifikate verwenden, die sich in Ihrem mailcow-Verzeichnis unter `data/web/inc/lib/WebAuthn/rootCertificates` befinden.
##### Beispiel:
Wenn Sie die offiziellen Hersteller-Geräte nur auf Apple beschränken wollen, brauchen Sie nur das Apple Hersteller-Zertifikat im `data/web/inc/lib/WebAuthn/rootCertificates`.
Nachdem Sie alle anderen Zertifikate gelöscht haben, können Sie WebAuthn 2FA nur noch mit Apple-Geräten aktivieren.
Das ist für jeden Hersteller gleich, also wählen Sie aus, was Ihnen gefällt (wenn Sie es wollen).
#### Eigene Zertifikate fĂĽr WebAuthn verwenden
Wenn du ein gĂĽltiges Zertifikat vom Hersteller deines SchlĂĽssels hast, kannst du es auch zu deiner Mailcow hinzufĂĽgen!
Kopieren Sie einfach das Zertifikat in den `data/web/inc/lib/WebAuthn/rootCertificates` Ordner und starten Sie Ihre Mailcow neu.
Nun sollten Sie in der Lage sein, auch dieses Gerät zu registrieren, obwohl die Überprüfung für die Herstellerzertifikate aktiviert ist, da Sie das Zertifikat manuell hinzugefügt haben.
#### Ist es gefährlich, den Vendor Check deaktiviert zu lassen?
Nein, das ist es nicht!
Diese Herstellerzertifikate werden nur zur ĂśberprĂĽfung der Originalhardware verwendet, nicht zur Absicherung des Registrierungsprozesses.
Wie Sie in diesen Artikeln lesen können, hat die Deaktivierung nichts mit der Software-Sicherheit zu tun:
- [https://developers.yubico.com/U2F/Attestation_and_Metadata/](https://developers.yubico.com/U2F/Attestation_and_Metadata/)
- [https://medium.com/webauthnworks/webauthn-fido2-demystifying-attestation-and-mds-efc3b3cb3651](https://medium.com/webauthnworks/webauthn-fido2-demystifying-attestation-and-mds-efc3b3cb3651)
- [https://medium.com/webauthnworks/sorting-fido-ctap-webauthn-terminology-7d32067c0b01](https://medium.com/webauthnworks/sorting-fido-ctap-webauthn-terminology-7d32067c0b01)
Letztendlich ist es aber natürlich Ihre Entscheidung, ob Sie dieses Häkchen deaktiviert oder aktiviert lassen.
---
## TOTP
Die bekannteste TFA-Methode, die meist mit einem Smartphone verwendet wird.
Um die TOTP-Methode einzurichten, loggen Sie sich in die Admin UI ein und wählen Sie `Time-based OTP (TOTP)` aus der Liste.
Nun öffnet sich ein Modal, in dem Sie einen Namen für Ihr 2FA-"Gerät" (Beispiel: John Deer's Smartphone) und das Passwort des betroffenen Admin-Kontos (mit dem Sie derzeit eingeloggt sind) eingeben müssen.
Sie haben zwei verschiedene Methoden, um TOTP fĂĽr Ihr Konto zu registrieren:
1. Scannen Sie den QR-Code mit Ihrer Authenticator App auf einem Smartphone oder Tablet.
2. Verwenden Sie den TOTP-Code (unter dem QR-Code) in Ihrem TOTP-Programm oder Ihrer App (wenn Sie keinen QR-Code scannen können).
Nachdem Sie den QR- oder TOTP-Code in der TOTP-App/dem TOTP-Programm Ihrer Wahl registriert haben, müssen Sie nur noch den nun generierten TOTP-Token (in der App/dem Programm) als Bestätigung in der mailcow UI eingeben, um die TOTP 2FA endgültig zu aktivieren, ansonsten wird sie nicht aktiviert, obwohl der TOTP-Token bereits in Ihrer App/ Ihrem Programm generiert wurde.

Datei anzeigen

@ -0,0 +1,123 @@
So far three methods for _Two-Factor Authentication_ are implemented: WebAuthn (replacing U2F since February 2022), Yubi OTP, and TOTP
- For WebAuthn to work, you need an encrypted connection to the server (HTTPS) as well as a FIDO security key.
- Both WebAuthn and Yubi OTP work well with the fantastic [Yubikey](https://www.yubico.com).
- While Yubi OTP needs an active internet connection and an API ID + key, WebAuthn will work with any Fido Security Key out of the box, but can only be used when mailcow is accessed over HTTPS.
- WebAuthn and Yubi OTP support multiple keys per user.
- As the third TFA method mailcow uses TOTP: time-based one-time passwords. Those passwords can be generated with apps like "Google Authenticator" after initially scanning a QR code or entering the given secret manually.
As administrator you are able to temporary disable a domain administrators TFA login until they successfully logged in.
The key used to login will be displayed in green, while other keys remain grey.
Information on how to remove 2FA can be found [here](../troubleshooting/debug-reset_pw.en.md#remove-two-factor-authentication).
## Yubi OTP
The Yubi API ID and Key will be checked against the Yubico Cloud API. When setting up TFA you will be asked for your personal API account for this key.
The API ID, API key and the first 12 characters (your YubiKeys ID in modhex) are stored in the MySQL table as secret.
### Example setup
First of all, the YubiKey must be configured for use as an OTP Generator. To do this, download the `YubiKey Manager` from the Yubico website: [here](https://www.yubico.com/support/download/)
In the following you configure the YubiKey for OTP.
Via the menu item `Applications` -> `OTP` and a click on the `Configure` button. In the following menu select `Credential Type` -> `Yubico OTP` and click on `Next`.
Set a checkmark in the `Use serial` checkbox, generate a `Private ID` and a `Secret key` via the buttons.
So that the YubiKey can be validated later, the checkmark in the `Upload` checkbox must also be set and then click on `Finish`.
Now a new browser window will open in which you have to enter an OTP of your YubiKey at the bottom of the form (click on the field and then tap on your YubiKey). Confirm the captcha and upload the information to the Yubico server by clicking 'Upload'. The processing of the data will take a moment.
After the generation was successful, you will be shown a `Client ID` and a `Secret key`, make a note of this information in a safe place.
Now you can select `Yubico OTP authentication` from the dropdown menu in the mailcow UI on the start page under `Access` -> `Two-factor authentication`.
In the dialog that opened now you can enter a name for this YubiKey and insert the `Client ID` you noted before as well as the `Secret key` into the fields provided.
Finally, enter your current account password and, after selecting the `Touch Yubikey` field, touch your YubiKey button.
Congratulations! You can now log in to the mailcow UI using your YubiKey!
---
## WebAuthn (U2F, replacement)
!!! warning
**Since February 2022 Google Chrome has discarded support for U2F and standardized the use of WebAuthn.<br>**
*The WebAuthn (U2F removal) is part of mailcow since 21th January 2022, so if you want to use the Key past February 2022 please consider a update with the `update.sh`*
To use WebAuthn, the browser must support this standard.
The following desktop browsers support this authentication type:
- Edge (>=18)
- Firefox (>=60)
- Chrome (>=67)
- Safari (>=13)
- Opera (>=54)
The following mobile browsers support this authentication type:
- Safari on iOS (>=14.5)
- Android Browser (>=97)
- Opera Mobile (>=64)
- Chrome for Android (>=97)
Sources: [caniuse.com](https://caniuse.com/webauthn), [blog.mozilla.org](https://blog.mozilla.org/security/2019/04/04/shipping-fido-u2f-api-support-in-firefox/)
WebAuthn works without an internet connection.
### What will happen to my registered Fido Security Key after the Update from U2F to WebAuthn?
!!! warning
With this new U2F replacement (WebAuthn) you have to re-register your Fido Security Key, thankfully WebAuthn is backwards compatible and supports the U2F protocol.
Ideally, the next time you log in (with the key), you should get a text box saying that your Fido Security Key has been removed due to the update to WebAuthn and deleted as a 2-factor authenticator.
But don't worry! You can simply re-register your existing key and use it as usual, you probably won't even notice a difference, except that your browser won't show the U2F deactivation message anymore.
### Disable unofficial supported Fido Security Keys
With WebAuthn there is the possibility to use only official Fido Security Keys (from the big brands like: Yubico, Apple, Nitro, Google, Huawei, Microsoft, etc.).
This is primarily for security purposes, as it allows administrators to ensure that only official hardware can be used in their environment.
To enable this feature, change the value `WEBAUTHN_ONLY_TRUSTED_VENDORS` in mailcow.conf from `n` to `y` and restart the affected containers with `docker-compose up -d`.
The mailcow will now use the Vendor Certificates located in your mailcow directory under `data/web/inc/lib/WebAuthn/rootCertificates`.
##### Example:
If you want to limit the official Vendor devices to Apple only you only need the Apple Vendor Certificate inside the `data/web/inc/lib/WebAuthn/rootCertificates`.
After you deleted all other certs you now only can activate WebAuthn 2FA with Apple devices.
That´s for every vendor the same, so choose what you like (if you want to).
#### Use own certificates for WebAuthn
If you have a valid certificate from the vendor of your key you can also add it to your mailcow!
Just copy the certificate into the `data/web/inc/lib/WebAuthn/rootCertificates` folder and restart your mailcow.
Now you should be able to register this device as well, even though the verification for the vendor certificates is enabled, since you just added the certificate manually.
#### Is it dangerous to keep the Vendor Check disabled?
No, it isn´t!
These vendor certificates are only used to verify original hardware, not to secure the registration process.
As you can read in these articles, the deactivation is not software security related:
- [https://developers.yubico.com/U2F/Attestation_and_Metadata/](https://developers.yubico.com/U2F/Attestation_and_Metadata/)
- [https://medium.com/webauthnworks/webauthn-fido2-demystifying-attestation-and-mds-efc3b3cb3651](https://medium.com/webauthnworks/webauthn-fido2-demystifying-attestation-and-mds-efc3b3cb3651)
- [https://medium.com/webauthnworks/sorting-fido-ctap-webauthn-terminology-7d32067c0b01](https://medium.com/webauthnworks/sorting-fido-ctap-webauthn-terminology-7d32067c0b01)
In the end, however, it is of course your decision to leave this check disabled or enabled.
---
## TOTP
The best known TFA method mostly used with a smartphone.
To setup the TOTP method login to the Admin UI and select `Time-based OTP (TOTP)` from the list.
Now a modal will open in which you have to type in a name for your 2FA "device" (example: John Deer´s Smartphone) and the password of the affected Admin account (you are currently logged in with).
You have two seperate methods to register TOTP to your account:
1. Scan the QR-Code with your Authenticator App on a Smartphone or Tablet.
2. Use the TOTP Code (under the QR Code) in your TOTP Program or App (if you can´t scan a QR Code).
After you have registered the QR or TOTP code in the TOTP app/program of your choice you only need to enter the now generated TOTP token (in the app/program) as confirmation in the mailcow UI to finally activate the TOTP 2FA, otherwise it will not be activated even though the TOTP token is already generated in your app/program.

Datei anzeigen

@ -75,15 +75,15 @@ nav:
- 'Recover accidentally deleted data': 'backup_restore/b_n_r-accidental_deletion.md' - 'Recover accidentally deleted data': 'backup_restore/b_n_r-accidental_deletion.md'
- 'Manual/Guides/Examples': - 'Manual/Guides/Examples':
- 'mailcow UI': - 'mailcow UI':
- 'Blacklist / Whitelist': 'u_e-mailcow_ui-bl_wl.md' - 'Blacklist / Whitelist': 'manual-guides/mailcow_UI/u_e-mailcow_ui-bl_wl.md'
- 'Configuration': 'u_e-mailcow_ui-config.md' - 'Configuration': 'manual-guides/mailcow_UI/u_e-mailcow_ui-config.md'
- 'CSS overrides': 'u_e-mailcow_ui-css.md' - 'CSS overrides': 'manual-guides/mailcow_UI/u_e-mailcow_ui-css.md'
- 'Pushover': 'u_e-mailcow_ui-pushover.md' - 'Pushover': 'manual-guides/mailcow_UI/u_e-mailcow_ui-pushover.md'
- 'Spamfilter': 'u_e-mailcow_ui-spamfilter.md' - 'Spamfilter': 'manual-guides/mailcow_UI/u_e-mailcow_ui-spamfilter.md'
- 'Tagging': 'u_e-mailcow_ui-tagging.md' - 'Tagging': 'manual-guides/mailcow_UI/u_e-mailcow_ui-tagging.md'
- 'Temporary email aliases': 'u_e-mailcow_ui-spamalias.md' - 'Temporary email aliases': 'manual-guides/mailcow_UI/u_e-mailcow_ui-spamalias.md'
- 'Two-Factor Authentication': 'u_e-mailcow_ui-tfa.md' - 'Two-Factor Authentication': 'manual-guides/mailcow_UI/u_e-mailcow_ui-tfa.md'
- 'WebAuthn / FIDO2': 'u_e-fido2.md' - 'WebAuthn / FIDO2': 'manual-guides/mailcow_UI/u_e-fido.md'
- 'Postfix': - 'Postfix':
- 'Add trusted networks': 'u_e-postfix-trust_networks.md' - 'Add trusted networks': 'u_e-postfix-trust_networks.md'
- 'Custom transport maps': 'u_e-postfix-custom_transport.md' - 'Custom transport maps': 'u_e-postfix-custom_transport.md'