Skip to content


Repository files navigation

Spring Boot reCAPTCHA v3 Starter

Maven Central CI Status License

Spring Boot starter for Google's reCAPTCHA v3.


repositories {

dependencies {

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.