Skip to content
Spring Boot reCAPTCHA v3 Starter
Branch: master
Clone or download
Latest commit 1416bb9 Nov 3, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
gradle/wrapper Initial commit Nov 3, 2019
src Initial commit Nov 3, 2019
.editorconfig Initial commit Nov 3, 2019
.gitignore Initial commit Nov 3, 2019
.travis.yml Initial commit Nov 3, 2019
LICENSE Initial commit Nov 3, 2019 Reorder README Nov 3, 2019
build.gradle.kts Initial commit Nov 3, 2019 [Gradle Release Plugin] - new version commit: '1.0.1-SNAPSHOT'. Nov 3, 2019
gradlew Initial commit Nov 3, 2019
gradlew.bat Initial commit Nov 3, 2019
settings.gradle.kts Initial commit Nov 3, 2019

Spring Boot reCAPTCHA v3 Starter

Release Build Status License

Spring Boot starter for Google's reCAPTCHA v3


repositories {
    maven { url = '' }

dependencies {
    compile 'com.michael-bull.spring-boot-starter-recaptcha:spring-boot-starter-recaptcha:1.0.0'

Getting Started

1. Register reCAPTCHA v3 keys

Register your application on the key registration page.

2. Add the configuration properties to your application.yaml:

  site: "<your site key>"
  secret: "<your secret key>"

3. Model the form that recaptcha exists on:

class RegisterForm {

    var recaptchaAction: String? = "register"

    var recaptchaResponseToken: String? = null

    var email: String? = null

4. Add a validator for your form:

class RegisterFormValidator @Inject constructor(
    private val request: HttpServletRequest,
    private val recaptchaValidator: RecaptchaValidator
) : Validator {

    override fun supports(clazz: Class<*>): Boolean {

    override fun validate(target: Any, errors: Errors) {
        val form = target as RecoverAccountForm
        val action = form.recaptchaAction
        val responseToken = form.recaptchaResponseToken

            .validate("recaptchaResponseToken", request, action, responseToken, errors)
            .onSuccess { (_, response) -> checkResponse(response, errors) }

    private fun checkResponse(response: SiteVerifyResponse, errors: Errors) {
        val score = response.score

        if (score != null && score < 0.2) {
            errors.rejectValue("recaptchaResponseToken", "Score too low")

5. Bind the validator in your Controller:

class RegisterController @Inject constructor(
    private val formValidator: RegisterFormValidator
) {

    fun initFormBinder(binder: WebDataBinder) {

    /* get and post handlers... */


Error codes generated by the RecaptchaValidator can be internationalized by adding the following entries to your

captcha.error.actionMissing=Captcha action missing.
captcha.error.incomplete=Captcha incomplete.
captcha.error.request=Failed to submit captcha.
captcha.error.responseMissing=No response from captcha service.
captcha.error.response=Error response from captcha service.
captcha.error.failed=Captcha failed. Please try again.
captcha.error.actionMismatch=Captcha action mismatch.


Bug reports and pull requests are welcome on GitHub.


This project is available under the terms of the ISC license. See the LICENSE file for the copyright information and licensing terms.

You can’t perform that action at this time.