This tutorial demonstrates how to integrate Google ReCaptcha into a Java Spring Web Application. reCAPTCHA is used to verify if the current computer is a human, preventing bots from automatically submitting forms. We integrated Google ReCaptcha using server side validation. We wrote a custom @ReCaptcha annotation which you can annotate your java fields. This’ll automatically handle the ReCaptcha server side validation process. At the bottom we also wrote some Unit and Integration tests using Mockito, spring-test and MockMvc.

Maven Dependencies

We use Apache Maven to manage our project dependencies. Make sure the following dependencies reside on the class-path.

Google ReCaptcha Settings

First, you need to request a google recaptcha account key and secret before you can start using the service. After you submitted your project, you’ll receive a key and secret. Add these in the application.yml property file below which is located in the src/main/resources folder.

Next, create a CaptchaSettings class which is used to map the properties located in the applicaiton.yml to. Annotate the class using the @ConfigurationProperties annotation and Spring Boot automatically maps the property to the object. You can read more over this in the Spring Boot @ConfigurationProperties Annotation Example tutorial.

Spring MVC RestTemplate Configuration

Since we are validating the reCAPTCHA server side, we need to communicate to the google api in order to validate the token. We used the RestTemplate which we configure using the Apache HttpClient.

Server Side Google ReCaptcha Validation

We need to validate the reCAPTCHA code received from the front-end component server-side. We need to make a request to and fill in the correct arguments obtained from the CaptchaSettings class which we created earlier. This’ll return a JSON response that’ll map to the ReCaptchaResponse class that we create next. Based on the result we pass the validation.

The ReCaptchaResponse is used to map the response received from the google reCAPTCHA API.

Creating ReCaptcha Field Annotation

Let’s create a custom @ValidCaptcha annotation. This is a field-level annotation which we can use to annotate a Java property.

The ReCaptchaConstraintValidator class is responsible for validating the input received from the annotated property.

Google ReCaptcha Request Parameter Problem

By default spring cannot map request parameters with hyphens. And since the google reCAPTCHA plugin returns the token inside the g-recaptcha-response request parameter, we need a way to solve this problem.

We opted to write a custom Filter which checks if the request contains the g-recaptcha-response request parameter and renames the request parameter to reCaptchaResponse without the hyphens.

Validating Form Submission

We created the ForgotPasswordForm to map the incoming form request parameters.
We can use this class to validate the incoming form parameters. We used the @ValidCaptcha annotation – which we created earlier – to automatically validate if the reCAPTCHA code sent from the client is valid.

Submitting Form Controller

We created a simple controller which processes the form and automatically validates the ForgotPasswordForm using the @Valid annotation.

Spring Boot

We use Spring Boot to start our application.

Integrate Google ReCaptcha in Web Application

You need to add the following javascript to your page.

Place the google reCAPTCHA code inside your form.

Here is an example forgot-password.html page which is located in the src/main/resources/templates/ folder.

Access the http://localhost:8080/forgot-password URL.

Integration Testing

To test our custom reCAPTCHA implementation we wrote some integration tests using Mockito to mock the ReCaptchaService, MockMvc to make http form requests.

We validate if the @ValidCaptcha annotation is triggering the validation.

This content was originally published here.