Spring Boot starter for Google's reCAPTCHA v3.
- Java 17 or later
- Spring Boot 4
repositories {
mavenCentral()
}
dependencies {
implementation("com.michael-bull.spring-boot-starter-recaptcha:spring-boot-starter-recaptcha:2.0.0")
}Register your application on the key registration page.
recaptcha.keys:
site: "<your site key>"
secret: "<your secret key>"class RegisterForm : RecaptchaForm {
override var recaptchaAction: String? = "register"
override var recaptchaResponseToken: String? = null
@Email
var email: String? = null
}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.
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.7To 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.
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.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.