Anmeldesicherheit und Zwei-Faktor-Pflicht

Wer heinzelhaus verwaltet, kann alle Bank- und Personendaten sehen. Deshalb gelten für die Anmeldung feste Regeln: Passwörter haben eine Mindestlänge, eine Sitzung läuft ab, Fehlversuche führen zu einer Sperre, und die Verwaltung der Installation verlangt eine starke Anmeldung. Diese Seite erklärt die Regeln für Administratoren und für die Person, die den Server betreut.

Damit Sie wissen, warum sich jemand nicht anmelden kann, und was Sie dann tun.

Sie brauchen: für die Einrichtung der starken Anmeldung ein Konto mit der Rolle „Administrator“. Für die Notfälle weiter unten zusätzlich Zugriff auf die Kommandozeile des Servers.

Was Ihre Mitarbeitenden bei der Anmeldung sehen, steht unter Anmelden und Ihr Profil und Ihre Sicherheit.

Auf einen Blick

Regel	Wert
Passwortlänge	Mindestens 12 Zeichen für neue und geänderte Passwörter. Ältere, kürzere Passwörter bleiben gültig, bis sie geändert werden.
Sitzung	Endet 12 Stunden nach der letzten Aktivität. Wer tagsüber arbeitet, wird nie abgemeldet, über Nacht läuft die Sitzung ab.
Kontosperre	Nach 10 falschen Passwörtern innerhalb von 15 Minuten ist die Passwort-Anmeldung dieses Kontos für 15 Minuten gesperrt.
Drosselung je Internetadresse	3 Anmeldeversuche je 10 Sekunden
Starke Anmeldung	Pflicht für Einstellungen, Benutzer und Rechte, Sicherungen und Updates
Code-Abfrage auf vertrauten Geräten	Wer es bei der Code-Abfrage wählt, wird auf diesem Gerät 30 Tage lang nicht nach einem Code gefragt

Passwörter und Sitzungen

Ein Passwort ändert jede Person selbst: im Benutzermenü oben rechts (Name oder Initialen) unter „Sicherheit“ in der Karte „Kennwort ändern“ mit „Aktuelles Kennwort“, „Neues Kennwort“ und „Neues Kennwort wiederholen“. Das geht auch unter „Mein Profil“. Dabei werden alle anderen angemeldeten Geräte abgemeldet.

Die Sitzungsdauer von 12 Stunden ist fest eingestellt. Abmelden kann sich jede Person über ihr Benutzermenü → „Abmelden“. Sperren Sie ein Konto, beendet heinzelhaus sofort alle seine Sitzungen, siehe Benutzer, Rollen und Rechte.

Die Kontosperre

Damit niemand ein Passwort durch Raten herausfindet.

Gezählt wird je E-Mail-Adresse, auch für Adressen ohne Konto. So verrät die Sperre nicht, welche Konten es gibt. Jeder Versuch wird schon vor der Prüfung gezählt und bei richtigem Passwort wieder zurückgenommen. Sonst kämen viele gleichzeitige Anfragen an der Sperre vorbei.

Was die Person sieht. „Zu viele fehlgeschlagene Anmeldeversuche für dieses Konto. Bitte in … Minuten erneut versuchen – oder mit Passkey anmelden.“
Wo sie noch wirkt. Überall, wo heinzelhaus das Passwort abfragt: bei der Anmeldung, beim Ändern des Kennworts sowie beim Einrichten und Abschalten der Authenticator-App. Auch ein falsches „Aktuelles Kennwort“ beim Ändern zählt als Fehlversuch.
Was weiter geht. Die Anmeldung mit Passkey bleibt möglich.
Wie lange. 15 Minuten. Die Sperre liegt nur im Arbeitsspeicher der Anwendung. Ein Neustart hebt alle Sperren auf.

Zusätzlich drosselt die Anmeldebibliothek jede Internetadresse. Die Kontosperre gibt es obendrein, weil sich die Adresse im Büronetz ohne vorgeschalteten Proxy fälschen lässt.

Wollen Sie die Sperre sofort aufheben, starten Sie die Anwendung auf dem Server neu, im Projektordner:

docker compose restart app

Ihre Daten bleiben dabei unberührt. Angefangene Eingaben Ihres Teams gehen aber verloren, und heinzelhaus ist für einen Moment nicht erreichbar. Sagen Sie Bescheid.

Die starke Anmeldung für die Verwaltung

Damit ein erratenes oder abgefangenes Passwort nicht genügt, um die Installation zu verändern.

Starke Anmeldung heißt: ein eingerichteter zweiter Faktor oder eine Anmeldung per Passkey. Ohne sie bleiben diese Bereiche zu:

die Einstellungen der Installation, mit Mailzugang, Schnittstellen, Sicherungen und Updates,
die Datenübernahme,
die Benutzerverwaltung: einladen, anlegen, Rollen vergeben, sperren.

Betroffen sind Konten mit der Rolle „Administrator“ und jede Person, die die Rechte „Einstellungen der Installation ändern“ oder „Benutzer einladen, Rollen vergeben, Konten sperren“ ausübt. Die Pflicht gilt auch für direkte Aufrufe der Benutzerverwaltungs-Schnittstelle, nicht nur in der Oberfläche. Die tägliche Arbeit in Buchhaltung, Objekten und Kontakten bleibt auch ohne starke Anmeldung möglich. Die Pflicht sperrt niemanden aus. Sie verlangt die Einrichtung dort, wo die Installation selbst verändert wird.

Öffnet ein Administrator ohne starke Anmeldung die Einstellungen, landet er auf der Seite „Sicherheit“. Dort steht der Hinweis „Einstellungen und Updates: Bitte stark anmelden“ mit den zwei Wegen.

Weg A: Passkey

Damit die Anmeldung per Fingerabdruck, Gesichtserkennung, Windows Hello oder Sicherheitsschlüssel geht, ohne Code.

Öffnen Sie im Benutzermenü oben rechts „Sicherheit“.
Tragen Sie in der Karte „Passkeys“ bei „Bezeichnung (optional)“ eine Bezeichnung ein, zum Beispiel „MacBook oder YubiKey“.
Klicken Sie auf „Passkey hinzufügen“ und bestätigen Sie im Fenster Ihres Browsers oder Betriebssystems. Es erscheint „Passkey hinzugefügt.“
Melden Sie sich ab und mit Passkey wieder an: Auf der Anmeldeseite wählen Sie „Mit Passkey anmelden“. Erst eine per Passkey begründete Anmeldung zählt. Der bloße Besitz eines Passkeys genügt nicht, solange eine Passwort-Anmeldung möglich ist.

heinzelhaus empfiehlt, mindestens zwei Passkeys auf verschiedenen Geräten zu hinterlegen. Geht das einzige Gerät verloren, bleibt sonst nur die Anmeldung per Passwort.

Weg B: Authenticator-App

Damit jede Passwort-Anmeldung zusätzlich einen Code aus einer App auf dem Handy verlangt. Geeignet sind zum Beispiel Aegis, 1Password sowie die Authenticator-Apps von Google oder Microsoft.

Öffnen Sie unter „Sicherheit“ die Karte „Zwei-Faktor-Authentifizierung“.
Geben Sie bei „Passwort bestätigen“ Ihr Passwort ein und klicken Sie auf „Einrichten“.
Scannen Sie unter „1. Code scannen“ den QR-Code mit der App. Gelingt das nicht, tragen Sie den darunter angezeigten Schlüssel von Hand ein.
Tragen Sie unter „2. Code aus der App eingeben“ den sechsstelligen Code ein und klicken Sie auf „Bestätigen“. Es erscheint „Zwei-Faktor-Authentifizierung aktiviert.“ und „Alle anderen Geräte wurden abgemeldet.“
Notieren Sie die Wiederherstellungscodes. Sie stehen im Hinweis „Wiederherstellungscodes sichern“. Jeder Code funktioniert einmal und ersetzt die App, falls das Gerät verloren geht. Sie werden später nicht mehr angezeigt.

Ab jetzt verlangt jede Anmeldung mit Passwort den Code. Abschalten können Sie die Authenticator-App wieder unter „Zwei-Faktor-Authentifizierung“: Passwort eingeben, „Abschalten“. Die Pflicht bleibt dann bestehen, der Administrator braucht wieder eine starke Anmeldung.

Passkeys, Domain und https

Ein Passkey ist an die Internetadresse (Domain) gebunden, unter der Ihre Installation läuft, und setzt eine verschlüsselte Verbindung (https) voraus.

Der Eintrag PASSKEY_RP_ID in der .env muss die Domain nennen, ohne https:// und ohne Port. Das Installationsskript setzt ihn, wenn Sie bei der Installation eine Domain gewählt haben. Ohne Eintrag gilt localhost.
Stimmt PASSKEY_RP_ID nicht zur aufgerufenen Adresse, verweigert der Browser die Anmeldung ohne verwertbare Fehlermeldung.
Bei einer Installation im lokalen Netz über eine IP-Adresse stehen Passkeys in der Regel nicht zur Verfügung. Dort bleibt für die starke Anmeldung die Authenticator-App.
Ändern Sie die Domain, gelten bestehende Passkeys nicht mehr. Die Personen richten sie neu ein.

Läuft heinzelhaus über reines http auf einer Netzadresse, sehen Administratoren unter „Sicherheit“ den Hinweis „Verbindung ist unverschlüsselt“. Anmeldung und Sitzung gehen dann im Klartext durchs Netz. Abhilfe schafft https vor der Anwendung, siehe Installation.

Gerät verloren: den zweiten Faktor zurücksetzen

Damit jemand wieder hineinkommt, dessen Handy mit der Authenticator-App verloren ist.

Der einfache Weg: Die Person meldet sich auf der Anmeldeseite mit einem Wiederherstellungscode an: „Kein Zugriff auf die App? Wiederherstellungscode verwenden“. Jeder Code gilt einmal. Siehe Anmelden.

Der Weg für den Notfall: Hat die Person auch keine Wiederherstellungscodes mehr, nimmt die Betreuung des Servers dem Konto den zweiten Faktor ab. Sie brauchen Zugriff auf die Kommandozeile des Servers (wer ihn hat, hat ohnehin Zugriff auf die Datenbank; das Skript öffnet also keine neue Tür).

Rufen Sie im Projektordner das Skript mit der E-Mail-Adresse des Kontos auf:
Terminal-Fenster
```
./scripts/2fa-zuruecksetzen.sh name@verwaltung.de
```
Das Skript zeigt das Konto (Name, E-Mail, Rolle) und erklärt: „Entfernt wird der zweite Faktor samt Wiederherstellungscodes; alle Sitzungen des Kontos werden beendet (das verlorene Gerät könnte noch angemeldet sein). Passwort und Passkeys bleiben unverändert.“
Bestätigen Sie die Frage „Fortfahren? [ja/nein]“ mit ja.
Es meldet „Erledigt.“ Die Person meldet sich mit dem Passwort an und richtet den zweiten Faktor unter „Sicherheit“ neu ein. Für Administratoren ist er Pflicht.

Läuft die Datenbank nicht in Docker, rufen Sie das Skript mit PSQL="psql heinzelhaus" ./scripts/2fa-zuruecksetzen.sh name@verwaltung.de auf.

Die Pflicht abschalten

Betreiben Sie eine Installation bewusst ohne zweiten Faktor, heben Sie die Pflicht mit einem Eintrag in der .env auf:

HH_2FA_PFLICHT=aus

Übernehmen Sie die Änderung mit docker compose up -d im Projektordner (bei Betrieb mit Domain mit allen Compose-Dateien, siehe Installation). Der alte Name CASA_2FA_PFLICHT wird weiter gelesen, wenn HH_2FA_PFLICHT fehlt. Der Eintrag hebt nur die Pflicht auf. Die Code-Abfrage bei der Anmeldung bleibt für jedes Konto mit eingerichtetem zweitem Faktor bestehen.

Häufige Fehler

Meldung oder Situation	Ursache	Lösung
„Zu viele fehlgeschlagene Anmeldeversuche für dieses Konto. Bitte in … Minuten erneut versuchen – oder mit Passkey anmelden.“	Die Kontosperre greift.	Warten Sie, melden Sie sich mit Passkey an oder starten Sie die Anwendung neu, siehe oben.
„Anmeldung vorübergehend gesperrt“ mit dem Zusatz „Zu viele Anmeldeversuche. Bitte in einigen Minuten erneut versuchen.“	Von derselben Internetadresse kamen zu schnell viele Versuche.	Warten Sie einige Minuten.
„Kennwort nicht geändert“ mit dem Zusatz „Das aktuelle Kennwort stimmt nicht.“	Beim Ändern des Kennworts ist das „Aktuelle Kennwort“ falsch.	Geben Sie das aktuelle Kennwort noch einmal ein. Der Fehlversuch zählt für die Kontosperre.
„Einstellungen und Updates: Bitte stark anmelden“	Dem Administrator fehlt die starke Anmeldung.	Richten Sie einen Passkey oder die Authenticator-App ein und melden Sie sich neu an.
„Für diesen Bereich braucht es eine starke Anmeldung: mit Passkey anmelden oder unter „Sicherheit“ die Authenticator-App einrichten.“	Eine Aktion in den Einstellungen wurde ohne starke Anmeldung versucht.	Wie oben.
Passkey wird abgelehnt, ohne Meldung	`PASSKEY_RP_ID` passt nicht zur Adresse, oder die Verbindung ist nicht https.	Prüfen Sie `PASSKEY_RP_ID` und die Adresse.
Der Code der Authenticator-App wird nicht akzeptiert	Der Code ist abgelaufen, die Uhr des Handys geht falsch, oder `BETTER_AUTH_SECRET` ist ein anderer als bei der Einrichtung.	Prüfen Sie die Uhr. Hilft das nicht, setzen Sie den zweiten Faktor zurück.

Noch nicht möglich

„Passwort vergessen“. Es gibt keine Funktion zum Zurücksetzen eines vergessenen Passworts, und kein Administrator kann das Passwort einer anderen Person neu setzen. Ein Passkey ist der Ausweg.
Neue Wiederherstellungscodes erzeugen. Die Codes erscheinen nur bei der Einrichtung der Authenticator-App. Brauchen Sie neue, schalten Sie die App unter „Zwei-Faktor-Authentifizierung“ ab und richten Sie sie neu ein.
Den zweiten Faktor eines Kollegen in der Oberfläche zurücksetzen. Das geht nur auf dem Server mit dem Skript.
Eine Sperre in der Oberfläche aufheben. Die Sperre nach Fehlversuchen endet nach 15 Minuten oder mit einem Neustart der Anwendung.

Weiter geht es hier

Benutzer, Rollen und Rechte: Konten und Rechte verwalten.
Installation: https, Domain und Passkeys einrichten.
Datensicherung und Wiederherstellung: Warum die .env nicht fehlen darf.

heinzelhaus ist ein Produkt und eine Marke der IT Systeme Flores UG (haftungsbeschränkt), Bergisch Gladbach.