Konzepte

Wie wkidentity arbeitet: was das Paket führt, woran eine Absicherung hängt und warum die Abläufe so geschnitten sind. Was Sie tun wollen, steht auf Identity; was Sie nachschlagen wollen, in der Technischen Referenz.

wkidentity führt die Identität eines Kontos über seine ganze Lebensdauer. Zwei Gegenstände, die sich ein Paket teilen, weil sie dieselbe Frage beantworten — wer ist das:

• Zweiter Faktor. RFC-6238-TOTP (kompatibel mit Microsoft Authenticator, Google Authenticator und anderen Standard-Apps) als Selbstbedienung auf der Profilseite (do=profile), wahlweise ein Einmalcode per E-Mail, dazu eine Pflicht je Namensraum und eine optionale Abfrage beim Anmelden. Ergänzt um eine interne Testseite, die ein beliebiges Base32-Secret gegen die eigene TOTP-Rechnung prüft, ohne dass das Secret den Browser verlässt.
• Einmalcode-Abläufe. Kennwort-Zurücksetzen, Selbstregistrierung und Einladung durch einen Administrator — gebaut nach dem Grundsatz, dass niemand außer dem Kontoinhaber das Kennwort je kennt. Siehe Einmalcode-Abläufe.

Das Paket ist kein authtype: es ersetzt die Benutzerverwaltung nicht, sondern legt sich vor und neben sie.

isEnrolled() bleibt für immer wahr, sobald ein Faktor eingerichtet ist — eine Kontoeigenschaft ohne Zeitbezug. currentAssurance() beantwortet eine andere Frage: was diese Sitzung jetzt bewiesen hat. Ein seit Jahren eingerichtetes Konto kann eine Sitzung haben, die nie einen Step-up durchlaufen hat.

TOTP und MAIL_OTP sind Alternativen, keine Leiter — nur MFA_ANY als Anforderung akzeptiert beides. Ein Konto kann seit der Sicherheits-Härtung beide Faktoren gleichzeitig führen (unabhängig voneinander einrichtbar/entfernbar); eine einzelne Sitzung beweist trotzdem immer nur einen konkreten davon.

Eine bewiesene Stufe läuft jetzt ab. Die Einstellung assurance_ttl (Vorgabe 3600 Sekunden) bestimmt, wie lange ein abgeschlossener Step-up — oder ein beim Login bewiesener Faktor — als Absicherung dieser Sitzung zählt, bevor er auf AUTHENTICATED zurückfällt (nicht auf NONE: die Anmeldung selbst bleibt bestehen, nur der zusätzliche Faktornachweis verfällt). Das ersetzt die frühere Festlegung „keine Stufe verfällt innerhalb einer Sitzung“.

Bislang nicht existent: jede Weiterleitung in LoginGate/action.php führte bedingungslos auf $conf['start'], nie zurück zum ursprünglichen Ziel. Neu: require() leitet bei Bedarf auf do=wkidentity_stepup um — dieselbe Formularschale wie do=wkidentity_verify (Wiederverwendung von verifyCode()/verifyEmailChallenge(), keine neue Kryptographie) — und kehrt nach einem korrekten Code zum geprüften Ziel zurück.

Seit der Sicherheits-Härtung berücksichtigt PolicyStore vier unabhängige Achsen statt nur Namespace: namespace (Präfix-Vergleich wie conf/acl.auth.php), group (jede Gruppe der aktuellen Sitzung), user (genauer Login) sowie plugin/module/view/command/ adminAction (genaue Id, vom aufrufenden Plugin selbst benannt). Eine Anfrage kann mehreren Achsen gleichzeitig unterliegen — PolicyStore::effectiveRequirement($scope, $user, $groups) faltet jeden zutreffenden Eintrag über PolicyStore::combine() zusammen.

Ein Namespace, der nur in der älteren required_namespaces-Liste benannt ist (die vor required_scopes entstand und keine eigene Anforderungsstufe trägt), löst weiterhin — zurückgestuft auf MFA_ANY — auf: die naheliegendste treue Lesart dessen, was diese Liste immer bedeutet hat („ein beliebiger enrollter Faktor genügt„), jetzt geprüft gegen echte Sitzungs-Absicherung statt bloße Kontoeinschreibung.

Das Enrollment ist bewusst ein Zwei-Schritt-Vorgang und kein Instant-On, damit ein Nutzer 2FA nie mit einem Secret „aktiviert“, das seine Authenticator-App tatsächlich nie gescannt hat:

1. Start — Button „Einrichten“ auf do=profile (nur sichtbar, wenn noch nicht enrollt). Erzeugt ein neues Zufalls-Secret (auth_randombytes(), 160 Bit) und legt es nur in der Session ab — noch nichts wird auf Platte geschrieben.
2. Bestätigen — die Seite rendert QR-Code + manuelles Secret + ein Eingabefeld für den 6-stelligen Code. Erst ein korrekter Code (gegen das Pending-Secret geprüft, ±1 Zeitschritt Toleranz) persistiert das Secret verschlüsselt (saveSecret()) und löscht den Pending-Eintrag aus der Session. Ein falscher Code lässt das Pending-Secret unangetastet — der Nutzer kann denselben QR-Code erneut scannen/eingeben.
3. Status/Deaktivieren — sobald enrollt, zeigt die Profilseite nur noch Status „aktiv“ + eine Checkbox „Deaktivieren“, die zusammen mit dem regulären Profil-„Speichern“-Button das Secret entfernt (removeSecret()).

Die interne Testseite (do=wkidentity_debug, Link im Profil optional über die Einstellung show_debug_link) ist vom echten Enrollment komplett entkoppelt: Sie berechnet TOTP-Codes zu einem beliebig eingefügten Secret rein im Browser (Web Crypto HMAC-SHA1) und schickt nie etwas an den Server — gedacht, um die Kompatibilität mit Authenticator-Apps zu prüfen, nicht um echte Nutzer-Secrets anzuzeigen.

Zweiter Reiter im selben 2FA-Bereich, nur sichtbar wenn die Einstellung allow_email_method aktiv ist (Default aus, siehe „Konfiguration“). Derselbe Zwei-Schritt-Grundsatz wie bei TOTP: „Per Email einrichten„ schickt einen 6-stelligen Code an die aktuell im Profil hinterlegte Adresse (sendEmailChallenge(), gesalzener Hash — password_hash(), seit der Sicherheits-Härtung, zuvor ungesalzenes SHA-256 — mit 10 Minuten Ablauf server-seitig gespeichert, nie im Klartext); erst ein korrekt eingegebener Code aktiviert die Methode (saveEmailMethod()). Seit der Sicherheits-Härtung kann ein Benutzer beide Methoden gleichzeitig führen — TOTP und Email —, unabhängig voneinander eingerichtet und entfernt (hasFactor()/enrolledFactors()/ removeFactor()); eine einzelne Anmeldung oder ein Step-up akzeptiert dabei, welcher der eingerichteten Faktoren auch immer zum eingegebenen Code passt.

Umgesetzt über LoginGate.php und den Kern-Hook AUTH_LOGIN_CHECK (inc/auth.php, vor der eigentlichen Session-Finalisierung) — der einzige Zeitpunkt im gesamten Request-Zyklus, an dem sich ein zusätzlicher Faktor vor den fertigen Login schieben lässt, da Cores auth_login() Passwort- Prüfung und Session-Aufbau sonst in einem Rutsch erledigt.

Ablauf: korrektes Passwort + Nutzer enrollt + Einstellung enforce_login aktiv → Login wird angehalten, ein Pending-Zustand (Nutzer, Passwort, eingerichtete Methoden, Ablauf, Fehlversuchszähler) landet für maximal login_attempt_window Sekunden in der Session (Reopen-Idiom, siehe oben), und die Seite do=wkidentity_verify verlangt den passenden Code (bei zwei eingerichteten Methoden wird gegen beide geprüft, siehe „Assurance ist eine Sitzungs-, keine Kontoeigenschaft“ oben). Bei Erfolg wird der echte Core-Login (auth_login()) selbst ausgelöst — keine eigene Session-/Cookie-Logik, volle Wiederverwendung — und zusätzlich die Sitzungs-Absicherung vermerkt (StepUp::recordAssurance()): ein beim Login bewiesener Faktor zählt seither genauso wie ein per Step-up bewiesener, statt eine sofortige, überflüssige erneute Abfrage zu erzwingen. Bei login_max_attempts Fehlversuchen wird der Pending-Zustand verworfen; der Nutzer muss erneut mit Passwort beginnen.

Nicht enrollte Nutzer sind vollständig unberührt — gateLogin() greift nur bei bereits enrollten Nutzern ein; wer nie 2FA eingerichtet hat, meldet sich unverändert einstufig an, auch bei aktivem enforce_login.

Drei Vorgänge, ein Mechanismus: Kennwort-Zurücksetzen, Selbstregistrierung und Einladung durch einen Administrator. Alle drei enden damit, dass der Kontoinhaber sein Kennwort selbst eingibt — es wird nie erzeugt, nie versendet und nie angezeigt.

Ein- und ausgeschaltet über otp_flows (Vorgabe an).

Ohne sie liest sich die Einstellungsliste wie fünf beliebige Zeitwerte:

1. Der Code ist nicht der Vorgang. Ein Code lebt otp_ttl Sekunden (Vorgabe 1800), der Vorgang selbst reset_ttl / register_ttl / invite_ttl (Vorgabe 1 Tag / 2 Tage / 7 Tage). Deshalb kann ein neuer Code angefordert werden, ohne von vorn zu beginnen — die verschickte E-Mail darf verloren gehen, der Vorgang überlebt sie. Ein Code in einem Postfach ist ein Schlüssel in einer Tür, also ist er kurzlebig; der Vorgang ist es nicht.
2. Was Raten begrenzt, ist das Versuchsbudget, nicht die Codelänge. otp_attempts (Vorgabe 5) zählt je Vorgang, und ein neuer Code füllt es nicht auf. Wer den Nachschub-Knopf drückt, bekommt keinen zweiten Satz Versuche. otp_resend_gap (Vorgabe 60 s) begrenzt zusätzlich, wie oft überhaupt nachgeschickt wird.

Nichts. requestReset() antwortet gleich, ob es das Konto gibt oder nicht — sonst wäre das Zurücksetz-Formular ein Mitgliedschafts-Prüfer, in den jeder beliebige Namen eintippen kann.

Aus demselben Grund ist die Formulierung auf dem Bildschirm für alle dieselbe: sie leitet sich nur aus wikiweitem Zustand ab, nie aus dem eingegebenen Namen. Eine Wortwahl, die dem einzelnen Konto folgte, verriete, welche Namen einen Authentifikator halten.

Für den Fall, den kein Formular lösen kann — totp ist gesetzt und das Konto hat keinen Authentifikator, oder die E-Mail kommt nachweislich nicht an:

• Über die Einladungs-Verwaltung (Technische Referenz) oder die Kommandozeile stellt ein Administrator einen Code aus. Dieser Weg öffnet absichtlich einen Vorgang mit gemailtem Code, unabhängig von recovery_factor — er ist der Ausweg, und ein Ausweg, der derselben Richtlinie unterläge wie der Weg hinein, wäre keiner.
• Der Code wird dem Administrator genau einmal angezeigt, in der Antwort auf die Anforderung, und nirgends abgelegt, wo er ein zweites Mal erscheinen könnte.
• Der Mindestabstand für Nachschub entfällt hier: eine Rettung eine Minute warten zu lassen, nachdem der Gerettete sich vertippt hat, ist das Gegenteil ihres Zwecks.
• Ein Code berechtigt zum Setzen eines Kennworts und offenbart keines. Ein Administrator hält damit keine Zugangsdaten in der Hand.

• At-Rest-Verschlüsselung — Secrets liegen nie im Klartext auf Platte (Technische Referenz: Speicherung); Email-Codes liegen nur gesalzen gehasht (password_hash(), seit der Sicherheits-Härtung).
• TOTP-Wiederverwendung ausgeschlossen (seit der Sicherheits-Härtung) — ein einmal akzeptierter Zeitschritt wird für dasselbe Login nicht ein zweites Mal angenommen, über jeden Aufrufer von verifyCode() hinweg (Login, Step-up, Enrollment-Bestätigung, Kennwort-Wiederherstellung).
• CSRF — jeder Submit auf do=profile, im Admin-Panel und auf do=wkidentity_verify prüft checkSecurityToken() (CWE-352).
• XSS — alle ausgegebenen Werte (Secret, URI, Login) via hsc() (CWE-79).
• Zwei-Schritt-Enrollment — verhindert „Aktivieren“ ohne nachgewiesenen Scan/Empfang (siehe Workflow), für beide Methoden.
• Login-Erzwingung als Kill-Switch — enforce_login ist ein einfacher, vom eigenen Admin-Panel unabhängiger onoff-Schalter, sofort abschaltbar.
• Rate-Limiting — sessiongebundener Fehlversuchszähler auf do=wkidentity_verify (kein IP-Tracking, bewusst einfach gehalten).
• Debug-Tool — nur für angemeldete Nutzer erreichbar; Secret-Berechnung rein clientseitig, nichts wird je an den Server gesendet.
• Erstes AUTH_ACL_CHECK-Plugin in diesem Repository — verschärft nur zusätzlich, mutiert niemals conf/acl.auth.php.
• Kein Kennwort verlässt je den Server — die Einmalcode-Abläufe erzeugen und versenden keines; der Kontoinhaber tippt sein Kennwort selbst, und die Mindestlänge wird serverseitig geprüft.
• Codes nur gehasht — auch in den Vorgangsdateien; ein Administrator kann einen Code ausstellen, aber keinen nachschlagen.
• Keine Kontoauskunft — das Zurücksetz-Formular antwortet gleich, ob es das Konto gibt oder nicht, und seine Wortwahl leitet sich nie aus dem eingegebenen Namen ab.
• Kein Schreibvorgang auf GET — jeder zustandsändernde Zweig der Abläufe verlangt POST und Sicherheitstoken; ein GET zeichnet nur ein Formular. Ein Zurücksetzen, das ein Crawler durch Folgen eines Links auslösen könnte, wäre eines, das jeder für jeden auslösen kann.

• Identity — Einstieg und häufige Aufgaben
• Technische Referenz — Vertrag, Einstiege, Speicherung, Konfiguration, Klassen
• Fehlerdiagnose — Symptome mit Ursache und Abhilfe
• Der Aufforderungsbildschirm — warum er so gebaut ist, wie er gebaut ist
• Workbench Plugin Contract v1 — dessen permission-Feld dieser Vertrag einlöst