CaptchaService-Dokumentation

Dieses Handbuch ist der zentrale Einstiegspunkt auf GitHub Pages. Es ist mit dem Repository (main) versioniert.

• GitHub-Repository: https://github.com/it-at-m/captchaservice/
• Aktuelle Releases: github.com/it-at-m/captchaservice/releases
• Maven-Koordinaten: de.muenchen.captchaservice:backend

Schnellzugriff

• Projektgeschichte — warum es CaptchaService gibt und wo er heute eingesetzt wird
• Architektur — Komponentenübersicht
• Releases — Versionierung und Veröffentlichung von Artefakten
• Voraussetzungen
• Schnellstart — den Dienst lokal in Betrieb nehmen
• Widget-Demo — CaptchaService per ALTCHA-Widget im Browser testen
• Umgebungsvariablen
• Site-Konfiguration — mandantenfähige Sites, Geheimnisse und Schwierigkeits-Maps
• Challenge anlegen und Lösung prüfen
• Datenbank und Migrationen
• Monitoring

Über CaptchaService

CaptchaService ist ein Spring-Boot-Microservice, der Proof-of-Work-CAPTCHA-Challenges auf Basis der ALTCHA-Bibliothek bereitstellt — eine DSGVO-konforme, datenschutzfreundliche Alternative zu klassischen Bild-CAPTCHAs, in Europa entwickelt, ohne Cookies, ohne Tracking und ohne Drittanbieter-Aufrufe. Die Wahl einer quelloffenen, europäischen Bibliothek ist für uns ein bewusster Beitrag zur digitalen Souveränität der öffentlichen Verwaltung. CaptchaService ergänzt sie um adaptive Schwierigkeitssteuerung und Mehrmandantenfähigkeit.

CaptchaService ist die quelloffene Bot-Schutzschicht vor den öffentlichen ZMS-/eAppointment-APIs der Landeshauptstadt München. Er löst jahrelange Versuche mit eigenen und externen CAPTCHAs durch einen datenschutzfreundlichen Proof-of-Work-Ablauf ab, der vollständig auf dem Client läuft.

Funktionen

• Proof-of-Work-CAPTCHA: kryptografische Challenges via ALTCHA, keine Bilderrätsel.
• Adaptive Schwierigkeit: Schwierigkeit skaliert automatisch mit dem Anfrageverhalten der Quell-IP.
• Mehrmandantenfähigkeit: mehrere Sites parallel, je mit eigenem Schlüssel, Geheimnis und eigener Schwierigkeits-Map.
• Validierung der Quell-IP: IP-Filter und CIDR-Allowlisting.
• Geplante Bereinigung: abgelaufene Challenges und entwertete Payloads werden im Hintergrund entfernt.
• Monitoring: Health-Checks und Prometheus-Metriken über Spring Actuator.
• Persistenz: PostgreSQL-Speicherung mit automatisierten Flyway-Migrationen.

Technologien

• Java 21
• Spring Boot 3.x
• ALTCHA — Proof-of-Work-CAPTCHA-Bibliothek
• PostgreSQL 16+
• Flyway — Datenbankmigrationen
• Maven

Ablauf auf hoher Ebene

graph LR;
    Client[Client / Frontend] -->|POST /challenge| Service[CaptchaService];
    Service -->|signierte Challenge| Client;
    Client -->|löst PoW| Client;
    Client -->|POST /verify mit der Payload| Service;
    Service -->|gültig / ungültig| Client;
    Service -.->|speichern + bereinigen| DB[(PostgreSQL)];

Lizenz

Veröffentlicht unter der MIT-Lizenz.

Screenshot

CaptchaService im Einsatz auf der öffentlichen Terminbuchungsseite zmscitizenview der Landeshauptstadt München — eine unauffällige „Ich bin kein Bot“-Checkbox, hinterlegt mit einer ALTCHA-Proof-of-Work-Challenge.

Kontakt

Übersicht

Kontakt München: it@M – opensource@muenchen.de

CaptchaService wurde bei it@M, dem IT-Dienstleister der Landeshauptstadt München, entwickelt. Die vollständige Geschichte steht in der Projektgeschichte.