TrustComponent
Quarkus
TrustCaptcha · Bot-Schutz

Quarkus CAPTCHA-Integration

Binde ein Quarkus-CAPTCHA mit wenigen Zeilen Java in eine JAX-RS-Resource ein. Es stoppt Bot-Spam bei Logins, Registrierungen und Kontaktformularen. Die Integration läuft auch im Native Image und arbeitet mit MicroProfile Config und Hibernate Validator. 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 Formular einbauen

Binde das TrustCaptcha-Widget in das HTML-Formular ein, das deine Quarkus-Resource ausliefert. Das Widget läuft im Hintergrund und fügt beim Absenden ein verstecktes Feld tc-verification-token hinzu, das Quarkus deiner @POST-Methode über @FormParam zur Verfügung stellt.

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

<form method="post" action="/contact">
    <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 deiner Quarkus-Resource validieren

Hole in deiner Quarkus-Resource 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 deiner JAX-RS-Resource und reagiere auf das Ergebnis:

ContactResource.java
Java
@Path("/contact")
public class ContactResource {

  @POST
  public Response submit(@FormParam("tc-verification-token") String token) {

    VerificationResult result;
    try {
      result = TrustCaptcha.getVerificationResult("<your_api_key>", token);
    } catch (CaptchaFailureException e) {
      return Response.status(400).entity("CAPTCHA verification failed.").build();
    }

    if (!result.isVerificationPassed() || result.getScore() > 0.5) {
      return Response.status(400).entity("CAPTCHA verification failed.").build();
    }

    // CAPTCHA bestanden — Anfrage verarbeiten
    return Response.ok("Thanks!").build();
  }
}

Detaillierte Informationen zur Quarkus-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 Quarkus?
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

Funktioniert das Quarkus-CAPTCHA mit quarkus-rest und dem älteren RESTEasy Classic?
Ja, beide funktionieren gleich. Die Verifizierung ist ein normaler Java-Methodenaufruf in deiner @POST-Resource-Methode. Ob du quarkus-rest (RESTEasy Reactive) oder quarkus-resteasy-classic verwendest, ändert nur den Dependency-Namen, nicht den Integrationscode.
Wie lese ich den CAPTCHA-Token in einer JAX-RS-Resource?
Er kommt als regulärer Form-Parameter mit dem Namen "tc-verification-token" an. Annotiere den Methodenparameter mit @FormParam("tc-verification-token"), und Quarkus liefert dir den Wert als String.
Kann ich die CAPTCHA-Prüfung in den Hibernate Validator (@Valid) einhängen?
Ja. Für Projekte mit mehreren geschützten Endpunkten baust du eine eigene Bean-Validation-Constraint (z. B. @TrustCaptchaToken) mit einem CDI-verwalteten @ApplicationScoped-Validator, der den API-Key über @ConfigProperty injiziert. Die Prüfung läuft dann automatisch, wenn du einen Parameter mit @Valid markierst.
Wo speichere ich den CAPTCHA-API-Key in einer Quarkus-App?
Lege ihn in application.properties unter einem Schlüssel wie trustcaptcha.api-key ab und lies ihn mit @ConfigProperty(name = "trustcaptcha.api-key") aus. In Produktion füllst du den Wert aus einer Umgebungsvariable oder deinem Secret Manager, so landet der Key nie im Repo.
Funktioniert TrustCaptcha in einem Quarkus Native Image (GraalVM)?
Ja. Das Java-SDK funktioniert im JVM-Modus und in Native Builds. Mit quarkus-jackson auf dem Classpath werden die Reflection-Metadaten des Result-Typs automatisch registriert. Für typische Setups ist keine zusätzliche Konfiguration nötig.
Was ist mit reaktiven Endpoints, die Uni oder Multi zurückgeben?
Der Java-SDK-Aufruf ist blockierend, daher kapselst du ihn in einer reaktiven Resource mit Uni.createFrom().item(...).runSubscriptionOn(Infrastructure.getDefaultWorkerPool()). So bleibt der I/O-Thread frei, während die Verifizierung läuft.
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 Quarkus-Anwendung in wenigen Schritten mit TrustCaptcha!

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