Skip to content

About

Spring Boot starter for Google's reCAPTCHA v3.

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Repository files navigation

Spring Boot reCAPTCHA v3 Starter

Maven Central CI License

Spring Boot starter for Google's reCAPTCHA v3.

Requirements

  • Java 17 or later
  • Spring Boot 4

Installation

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.michael-bull.spring-boot-starter-recaptcha:spring-boot-starter-recaptcha:2.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:

recaptcha.keys:
  site: "<your site key>"
  secret: "<your secret key>"

3. Model the form that recaptcha exists on:

class RegisterForm : RecaptchaForm {

    override var recaptchaAction: String? = "register"

    override var recaptchaResponseToken: String? = null

    @Email
    var email: String? = null
}

4. Register the validator in your Controller:

The starter auto-configures a RecaptchaFormValidator that validates any RecaptchaForm. Add it in an @InitBinder method, alongside any of your own validators:

@Controller
class RegisterController @Inject constructor(
    private val recaptchaFormValidator: RecaptchaFormValidator
) {

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

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

If you need behaviour RecaptchaForm does not cover, skip it and write your own Validator that calls RecaptchaValidator.validate(...) directly, then register that instead.

Score

reCAPTCHA v3 scores each interaction from 0.0 (likely a bot) to 1.0 (likely a good interaction). The starter rejects interactions scoring below recaptcha.score-threshold, which defaults to 0.5, the starting threshold Google recommends ("By default, you can use a threshold of 0.5"):

recaptcha:
  score-threshold: 0.7

To decide acceptance using more than the score (for example the client IP address, hostname, or action), provide your own RecaptchaPolicy bean. The starter backs off its default ScoreThresholdPolicy when one is present:

@Component
class IpAwareRecaptchaPolicy : RecaptchaPolicy {

    override fun evaluate(exchange: SiteVerifyExchange): RecaptchaDecision {
        val score = exchange.response.score
        val ip = exchange.request.remoteIp

        return if (score != null && score >= 0.5 && ip !in blockedIps) {
            RecaptchaDecision.Accept
        } else {
            RecaptchaDecision.Reject("captcha.error.failed")
        }
    }
}

RecaptchaDecision.Reject takes an error code. If it names one of the bundled captcha.error.* keys the default message is used; otherwise your application's own messages.properties resolves it.

I18n

The starter bundles English default messages for the captcha.error.* codes, so form errors render out of the box with no configuration. To override the wording or provide translations, define the same keys in your application's messages.properties (your entries take precedence over the bundled defaults):

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.
captcha.error.score=Captcha score too low.

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.

About

Spring Boot starter for Google's reCAPTCHA v3.

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages