michaelbull / spring-boot-starter-recaptcha

Spring Boot starter for Google's reCAPTCHA v3.

Spring Boot reCAPTCHA v3 Starter

Spring Boot starter for Google's reCAPTCHA v3.

Installation

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.michael-bull.spring-boot-starter-recaptcha:spring-boot-starter-recaptcha:1.0.4")
}

Getting Started

1. Register reCAPTCHA v3 keys

Register your application on the key registration page.

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

recaptcha.keys:
  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

    @Email
    var email: String? = null
}

4. Add a validator for your form:

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

    override fun supports(clazz: Class<*>): Boolean {
        return RegisterForm::class.java.isAssignableFrom(clazz)
    }

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

        recaptchaValidator
            .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:

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

    @InitBinder("form")
    fun initFormBinder(binder: WebDataBinder) {
        binder.addValidators(formValidator)
    }

    /* get and post handlers... */
}

I18n

Error codes generated by the RecaptchaValidator can be internationalized by adding the following entries to your messages.properties:

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.

Contributing

Bug reports and pull requests are welcome on GitHub.

License

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