CaptchaService Documentation

This handbook is the main entry point on GitHub Pages. It is versioned with the repository (main).

• GitHub Repository: https://github.com/it-at-m/captchaservice/
• Latest releases: github.com/it-at-m/captchaservice/releases
• Maven coordinates: de.muenchen.captchaservice:captchaservice-backend

Quick Links

• Project History — why CaptchaService exists and where it is used today
• Architecture — high-level component diagram
• Releases — versioning and how artifacts are published
• Prerequisites
• Quick Start — get the service running locally
• Environment Variables
• Site Configuration — multi-tenant sites, secrets and difficulty maps
• Create Challenge and Verify Solution
• Database and Migrations
• Monitoring

About CaptchaService

CaptchaService is a Spring Boot microservice that provides proof-of-work CAPTCHA challenges using the ALTCHA library — a GDPR-compliant, privacy-first alternative to traditional image-based CAPTCHAs, made in Europe, with no cookies, no tracking, and no third-party calls. Picking an open-source, European library is a deliberate vote for digital sovereignty in the public sector. CaptchaService adds adaptive difficulty management and multi-tenant support on top.

CaptchaService is the open-source bot-protection layer in front of the public ZMS / eAppointment APIs operated by the City of Munich (Landeshauptstadt München). It replaces years of in-house and third-party CAPTCHA attempts with a privacy-friendly proof-of-work flow that runs entirely on the client.

Features

• Proof-of-Work CAPTCHA: ALTCHA-based crypto challenges, no image puzzles.
• Adaptive Difficulty: Difficulty scales automatically with the request pattern of a source address.
• Multi-Tenant Support: Multiple sites configured side by side, each with its own key, secret and difficulty map.
• Source Address Validation: IP-based filtering and CIDR allow-listing.
• Scheduled Cleanup: Expired challenges and invalidated payloads are removed in the background.
• Monitoring: Health checks and Prometheus metrics via Spring Actuator.
• Database Persistence: PostgreSQL storage with automated Flyway migrations.

Built With

• Java 21
• Spring Boot 3.x
• ALTCHA — proof-of-work CAPTCHA library
• PostgreSQL 16+
• Flyway — database migrations
• Maven

High-Level Flow

graph LR;
    Client[Client / Frontend] -->|POST /challenge| Service[CaptchaService];
    Service -->|signed challenge| Client;
    Client -->|solves PoW| Client;
    Client -->|POST /verify with payload| Service;
    Service -->|valid / invalid| Client;
    Service -.->|store + cleanup| DB[(PostgreSQL)];

License

Distributed under the MIT License.

Screenshot

CaptchaService in action on the public zmscitizenview appointment-booking page (Landeshauptstadt München) — an unobtrusive "Ich bin kein Bot" checkbox backed by an ALTCHA proof-of-work challenge.

Contact

Overview

Munich contact: it@M – opensource@muenchen.de

CaptchaService was built at it@M, the IT service provider of the Landeshauptstadt München. See Project History for the full story.