Ein TOTP-Code, ein Cookie, fertig: Warum ich clear-wicket gebaut habe

Problem

Wer selbst hostet, kennt die Situation: Ein internes Tool, ein Admin-Dashboard, ein Monitoring-Stack – irgendetwas, das nicht öffentlich erreichbar sein soll, aber trotzdem über eine Domain laufen muss, weil TLS und Traefik nun mal so funktionieren. Die Lösung dafür heißt "Forward-Auth" – Traefik schickt jede Anfrage erst an einen Auth-Dienst, bevor sie durchgelassen wird.

Das Problem: Jede etablierte Forward-Auth-Lösung, die ich mir angesehen habe – etwa Authelia oder Authentik – enthält einen eigenen ersten Faktor. Sprich: ein eigenes Passwortsystem, oft mit E-Mail-Recovery obendrauf.

Das klingt nach zusätzlicher Sicherheit, ist es aber nicht unbedingt. Denn E-Mail-Recovery bedeutet: Wer Zugriff auf das Postfach hat, kommt am zweiten Faktor vorbei. Die eigentliche Absicherung – TOTP nach RFC 6238, der Standard hinter jeder Authenticator-App – wird dadurch faktisch auf das Sicherheitsniveau des Mailkontos heruntergezogen. Das ist ein unnötig großes Rad, nur um eine einzige Frage zu beantworten: Bist du das, oder nicht? SMTP-Konfiguration, ein zweites Nutzerkonto-System, eine zusätzliche Angriffsfläche – für einen Faktor, der eigentlich einfach sein sollte.

Lösung

Also habe ich clear-wicket gebaut: ein leichtgewichtiges, passwortloses TOTP-Forward-Auth-Gateway für Traefik, geschrieben in Go.

Der Kerngedanke: Ein TOTP-Code, ein signiertes Session-Cookie, fertig. Kein eigenes Passwortsystem, kein SMTP, keine externen Laufzeit-Abhängigkeiten – kein Telemetrie-Aufruf, kein Update-Check, nichts, was nach Hause telefoniert.

Was drinsteckt:

• TOTP-Validierung nach RFC 6238 mit einstellbarer Toleranz für Uhrzeit-Drift
• Replay-Schutz – ein akzeptierter Code ist im selben Zeitfenster nicht wiederverwendbar
• Rate-Limiting mit exponentiellem Backoff nach Fehlversuchen
• Backup-Codes – zehn Einmal-Codes, als Argon2id-Hash gespeichert
• Signierte Session-Cookies (HMAC-SHA256, HttpOnly, Secure, SameSite=Lax) mit serverseitigem Session-Tracking, damit Logout auch wirklich etwas invalidiert

Bewusst NICHT drin: Passwort-Verwaltung, E-Mail-Recovery, eine eigene Nutzerdatenbank (V1 ist Single-User, Multi-User ist architektonisch vorbereitet, aber noch nicht umgesetzt). Wer den zweiten Faktor verliert, kommt über einen Backup-Code zurück – oder per Admin-Reset direkt auf der Maschine.

Der Einstieg ist ein Docker-Image unter 15 MB. Zur Einordnung: Authentik braucht allein für den Server rund 300 MB, dazu zusätzlich einen Worker-Container sowie PostgreSQL und Redis als Pflicht-Backend – ein deutlich größerer Unterbau. Authelia selbst ist mit rund 25 MB ebenfalls schlank, kommt aber mit eigener Storage-Konfiguration (SQLite/MySQL/PostgreSQL) und optionalem LDAP-Backend. clear-wicket braucht von alldem nichts – nur das eine Image plus ein Volume für den lokalen State. Dazu drei Zeilen Traefik-Labels, und ein Setup-Flow per QR-Code.

Für Setups mit mehreren Diensten gibt es zwei Varianten: eine gemeinsame Instanz mit einem TOTP-Code für alle Anwendungen einer Subdomain, oder eine isolierte Instanz pro Dienst – je nachdem, ob ein kompromittierter zweiter Faktor eine oder alle Anwendungen betreffen soll. Gerade die isolierte Variante lohnt sich dank der geringen Image-Größe ohne Weiteres: Mehrere clear-wicket-Instanzen auf demselben Host fallen kaum ins Gewicht.

Ergebnis

Ein Admin, der vor einen internen Dienst einen zweiten Faktor schalten will – ergänzend zur Basic-Auth, die viele Apps oder die Orchestrierungsebene (etwa Coolify) ohnehin mitbringen –, braucht ab jetzt keinen eigenen Nutzerverwaltungs-Stack mehr aufzusetzen. Ein docker-compose.yml-Block, ein Scan mit der Authenticator-App, fertig – Zugriff nur mit gültigem TOTP-Code, ohne dass irgendwo ein Passwort oder eine Mailbox im Spiel ist.

Für mich ist clear-wicket ein direktes Beispiel für das, wofür ich mit Clear Consulting LLC stehe: Die Lösung ist auf das Nötige reduziert, nachvollziehbar, quelloffen (Apache-2.0) – und macht mich als Berater in diesem Punkt entbehrlich, weil das Tool nach dem Setup einfach läuft.

Das Repository (inklusive vollständiger Konfigurationsreferenz, Sicherheitsmodell und Vergleichstabelle zu den etablierten Alternativen) liegt auf GitHub:

github.com/itsbrody/clear-wicket

Feedback, Issues und Forks sind ausdrücklich willkommen – dafür ist freie Software da.