TrustComponent
Spring Boot
TrustCaptcha · Bot-Schutz

Spring Boot CAPTCHA-Integration

Binde ein Spring Boot CAPTCHA mit wenigen Zeilen Java in einen Controller ein. Es stoppt Bot-Spam bei Logins, Registrierungen und Kontaktformularen, und Thymeleaf-Templates, Bean Validation und Spring Security bleiben, wie sie sind. EU-gehostet, DSGVO-konform und ohne Bilderrätsel.

Schnellstart

So funktioniert die Integration

1. CAPTCHA erstellen

Erstelle ein Benutzerkonto oder melde dich mit einem bestehenden Konto an. Dann erstellst du ein neues CAPTCHA oder wählst ein vorhandenes aus. Wenn du TrustCaptcha erst ausprobieren willst: Jeder Tarif startet mit einer 14-tägigen kostenlosen Testphase.

Auf der Übersichtsseite des CAPTCHAs findest du den Site Key und den License Key, und dort erstellst du auch deinen API-Key. Trage die Domains deiner Website in den Sicherheitsregeln des CAPTCHAs als autorisierte Domains ein, damit sie dein CAPTCHA nutzen dürfen.

Start des Formulars zur Erstellung eines CAPTCHA.
CAPTCHA-Sicherheitsregeln eines Demo-CAPTCHAs.

2. CAPTCHA-Widget in dein Thymeleaf-Template einbauen

Binde das TrustCaptcha-Widget in das Thymeleaf-Formular ein, das du schützen möchtest. Sobald ein Besucher mit dem Formular interagiert, läuft das CAPTCHA im Hintergrund und fügt beim Absenden ein verstecktes Feld tc-verification-token hinzu. Spring Boot übergibt es deinem Controller wie jeden anderen Form-Parameter.

contact.html
HTML
<script type="module" src="https://cdn.trustcomponent.com/trustcaptcha/3.0.x/trustcaptcha.esm.min.js"></script>

<form th:action="@{/contact}" method="post">
    <input type="email" name="email" required>
    <trustcaptcha-component sitekey="<your_site_key>"></trustcaptcha-component>
    <button type="submit">Send</button>
</form>

Das CAPTCHA-Widget wird anschließend in deinem Formular angezeigt:

CAPTCHA-Widget vor dem Start

Detaillierte Informationen zur CAPTCHA-Widget-Integration?
Die vollständige Widget-Referenz mit Themes, Sprachen, eigenem Design und mehr findest du in unserer Dokumentation.

Dokumentation lesen

3. Token in deinem Spring-Boot-Controller validieren

Hole in deinem Spring-Boot-Controller den Verifikationstoken aus dem Formular, rufe das Ergebnis über unsere Java-Library ab und entscheide, ob die Anfrage akzeptiert werden soll.

Installiere zunächst unsere TrustCaptcha-Java-Library:

pom.xml
XML
<dependency>
  <groupId>com.trustcomponent</groupId>
  <artifactId>trustcaptcha</artifactId>
  <version>3.0.0</version>
</dependency>

Validiere dann den Token in deinem Controller und reagiere auf das Ergebnis:

ContactController.java
Java
@PostMapping("/contact")
public String submit(@RequestParam("tc-verification-token") String token, Model model) {

  VerificationResult result;
  try {
    result = TrustCaptcha.getVerificationResult("<your_api_key>", token);
  } catch (CaptchaFailureException e) {
    return "contact"; // Verifizierung fehlgeschlagen — Formular erneut anzeigen
  }

  if (!result.isVerificationPassed() || result.getScore() > 0.5) {
    return "contact"; // Sieht nach Bot aus — blockieren
  }

  // CAPTCHA bestanden — Anfrage verarbeiten
  return "contact-success";
}

Detaillierte Informationen zur Spring-Boot-CAPTCHA-Integration?
Die vollständige Schritt-für-Schritt-Anleitung inklusive Bean-Validation-Refactor für Projekte mit mehreren geschützten Endpunkten findest du in unserer Dokumentation.

Dokumentation lesen

Anderes Backend-Framework statt Spring Boot?
Wenn du ein anderes Framework nutzt, wähle hier das passende Rezept aus. Ist dein Framework nicht aufgeführt, können deine Softwareentwickler die Verifizierung mithilfe unserer Dokumentation selbst integrieren oder unser Support-Team nach einer vorgefertigten Integration fragen.

Actix Web
ASP.NET Core
Axum
Django
Echo
Express
FastAPI
Fastify
Fiber
Flask
Gin
Hapi
Laravel
Micronaut
NestJS
Next.js
Quarkus
Ruby on Rails
Sinatra
Spring Boot
Symfony

4. Integration testen

TrustCaptcha ist jetzt aktiv. Schick eine Testanfrage ab und prüfe, ob sie durchgeht.

CAPTCHA abgeschlossen

Häufige Fragen

Welche Spring-Boot-Versionen werden unterstützt?
TrustCaptcha läuft auf jeder modernen Spring-Boot-Version (2.x und 3.x). Die Verifizierung selbst ist ein normaler Java-Aufruf in deinem Controller, du brauchst also keinen Spring-Boot-Starter von uns.
Wo sollte die Spring Boot CAPTCHA-Prüfung stattfinden?
In der Controller-Methode, die das abgeschickte Formular empfängt, bevor du Daten speicherst oder eine E-Mail versendest. Der CAPTCHA-Token kommt als regulärer Form-Parameter (Standardname: "tc-verification-token") an, du liest ihn mit @RequestParam wie jedes andere Feld.
Funktioniert TrustCaptcha zusammen mit Spring Security?
Ja. TrustCaptcha sitzt auf der Anwendungsebene (dein Controller), unabhängig von Spring Security. Es ersetzt weder Authentifizierung, Autorisierung noch CSRF-Schutz. Lass diese aktiviert. Das CAPTCHA bestätigt nur, dass die Anfrage von einem Menschen stammt.
Kann ich die CAPTCHA-Validierung über Bean Validation (@Valid) auslösen?
Ja. Für Projekte mit mehreren geschützten Endpunkten ist eine eigene Bean-Validation-Annotation (z. B. @TrustCaptchaToken) auf einem DTO-Feld der sauberste Weg. Mit @Valid am Controller-Parameter läuft die Verifizierung automatisch in der normalen Validierungs-Pipeline mit.
Funktioniert TrustCaptcha mit WebFlux / reaktiven Controllern?
Ja. Das Java-SDK ist blockierend, daher kapselst du den Verifizierungs-Aufruf in einem reaktiven Endpoint mit Mono.fromCallable(...).subscribeOn(Schedulers.boundedElastic()), um den Event-Loop frei zu halten. Aus SDK-Sicht ändert sich nichts.
Wo speichere ich den CAPTCHA-API-Key in einem Spring-Boot-Projekt?
Behandle ihn wie jedes andere Secret: Lege ihn in application.yml oder application.properties unter einem Schlüssel wie trustcaptcha.api-key ab und injiziere ihn mit @Value("${trustcaptcha.api-key}"). In Produktion füllst du ihn aus einer Umgebungsvariable oder einem Secret Manager. Committe ihn niemals ins Repo.
Leads verlieren wegen CAPTCHAs?

TrustCaptcha blockiert Spam und Bots, nicht deine Kunden. Keine Rätsel, DSGVO-konform, in der EU gehostet.

CAPTCHA-Start
CAPTCHA abgeschlossen
Keine Rätsel für Besucher
Die Prüfung läuft im Hintergrund, während Besucher tippen. So schicken mehr Menschen deine Formulare ab, statt vorher aufzugeben.
DSGVO-konform
In der EU gehostet, ohne Cookies, mit verschlüsselter Übertragung und automatischer Löschung. Jeder Kunde bekommt einen Auftragsverarbeitungsvertrag (AVV).
Mehrstufige Sicherheit
Adaptiver Proof-of-Work und Risiko-Scoring stoppen Missbrauch früh, auch wenn der Angriffs-Traffic plötzlich steigt.
Volle Kontrolle
Stell die Empfindlichkeit ein, pflege Allow- und Blocklisten und nutze Geoblocking. Du entscheidest, wie streng die Prüfung ist.

Schütze deine Spring Boot-Anwendung in wenigen Schritten mit TrustCaptcha!

  • EU-hosted & DSGVO-konform
  • Keine Rätsel
  • 14 Tage kostenlos testen