Stop Bots for Free with Cloudflare Turnstile in your Spring Boot App

My First Spring Boot Library on Maven Central!

Hey everyone! I’m excited to share something I’ve been working on: a Spring Boot library that makes integrating Cloudflare’s Turnstile (their CAPTCHA alternative) super easy.

This is my first Spring Boot library published on Maven Central, so it’s just a pom.xml or build.gradle update away from being part of your Spring Boot project.  

What is Turnstile?

For those who might not know, Cloudflare’s Turnstile is a FREE CAPTCHA-like bot detection service that helps protect your site from malicious traffic. The best part? It’s frictionless for users. Turnstile can tell if you’re human without requiring you to pick out street signs or decipher squiggly letters.

Why This Library?

I’ve been using Cloudflare extensively for CDN, WAF, and now their Worker’s serverless edge compute platform in a lot of projects, and Turnstile is a pretty slick option for bot protection. Adding to a Spring Boot project is pretty easy, and it’s very small and simple for a standalone library, but my goal was to learn how to package Spring Boot code and configs as easily consumed libraries, and figure out how to publish libraries on Maven Central. So I wanted to start with something small and simple and easy to test. Bigger things will be coming!

This library provides a simple, drop-in solution for Spring Boot projects that want to integrate Turnstile for enhanced security. You just configure your application.yml, drop the library into your project, and you’re ready to roll.

How to Get Started

First off, you’ll need a Cloudflare account (obviously), and you’ll need to create a Turnstile widget to get your site key and secret. Once you have that, including the library in your project is as simple as adding a dependency:

For Maven:

<dependency>
    <groupId>com.digitalsanctuary</groupId>
    <artifactId>ds-spring-cf-turnstile</artifactId>
    <version>1.1.5</version>
</dependency>

For Gradle:

dependencies {
    implementation 'com.digitalsanctuary:ds-spring-cf-turnstile:1.1.5'
}

Configuration

Once you’ve got the library included in your project, configuring it is as easy as setting up your application.yml file:

ds:
  cf:
    turnstile:
      sitekey: your-site-key
      secret: your-secret

 Then, you just add the Turnstile widget into your HTML:

<form id="login-form" action="/login" method="post">
    <input type="email" name="email" placeholder="Email" required>
    <div class="cf-turnstile" data-sitekey="$YOUR_SITE_KEY"></div>
    <button type="submit">Login</button>
</form>

And on the backend, it’s all about validating that Turnstile response with a quick call to the TurnstileValidationService.

Here’s an example of how you can use it in a login controller to validate Turnstile tokens:

@Autowired
private TurnstileValidationService turnstileValidationService;

@PostMapping("/login")
public String login(@RequestParam String email,
                    @RequestParam("cf-turnstile-response") String turnstileResponse,
                    HttpServletRequest request) {
    String clientIpAddress = turnstileValidationService.getClientIpAddress(request);
    boolean turnstileValid = turnstileValidationService.validateTurnstileResponse(turnstileResponse, clientIpAddress);

    if (!turnstileValid) {
        log.error("Turnstile validation failed for email: " + email);
        return "error";
    }
    // Normal login logic here...
}

That’s it! The library takes care of handling the API request and response from Cloudflare’s servers, so you don’t have to mess with that directly.

Why Use This?

If you’re already using Spring Boot and want to add a quick layer of bot protection that integrates easily, this library is designed for you. It’s lightweight, easy to configure, and fits seamlessly into Spring Boot projects.

Next Steps

You can grab the library from Maven Central today and give it a spin. I’d love to hear your feedback and see how it helps with your projects.

Got questions or need support? Open an issue on the GitHub repo – I’m all ears!

Thanks for checking it out, and happy coding!