To use the starter you will need a reCAPTCHA site key and a secret key. To get them go to the reCAPTCHA Home Page and set up your reCAPTCHA.
repositories {
mavenCentral()
}
dependencies {
compile group: 'com.github.mkopylec', name: 'recaptcha-spring-boot-starter', version: '2.3.1'
}The starter can be used in 3 different modes:
Embed reCAPTCHA in HTML web page:
<html>
<head>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
...
</head>
<body>
<form action="/" method="post">
<div class="g-recaptcha" data-sitekey="<your_site_key>"></div>
<input type="submit" value="Validate reCAPTCHA" />
</form>
</body>
</html>Inject RecaptchaValidator into your controller and validate user reCAPTCHA response:
@Controller
public class MainController {
@Autowired
private RecaptchaValidator recaptchaValidator;
@PostMapping("/")
public void validateCaptcha(HttpServletRequest request) {
ValidationResult result = recaptchaValidator.validate(request);
if (result.isSuccess()) {
...
}
}
}Set your secret key in application.yml file:
recaptcha.validation.secret-key: <your_secret_key>RecaptchaValidator provides couple of useful methods to validate reCAPTCHA response.
Add Spring Security dependency:
dependencies {
compile group: 'org.springframework.boot', name: 'spring-boot-starter-security', version: '2.1.6.RELEASE'
}Embed reCAPTCHA in HTML login web page:
<html>
<head>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
...
</head>
<body>
<form action="/login" method="post">
User: <input name="username" type="text" value="" />
Password: <input name="password" type="password" value="" />
<!--<if request has 'showRecaptcha' query param>-->
<div class="g-recaptcha" data-sitekey="<your_site_key>"></div>
<!--</if>-->
<input type="submit" value="Log in" />
</form>
</body>
</html>Add reCAPTCHA support to your form login security configuration using FormLoginConfigurerEnhancer.
@Configuration
@EnableWebSecurity
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {
@Autowired
private FormLoginConfigurerEnhancer enhancer;
@Override
protected void configure(HttpSecurity http) throws Exception {
enhancer.addRecaptchaSupport(http.formLogin()).loginPage("/login")
.and()
.csrf().disable()
...
}
}Create custom login failures manager bean by extending LoginFailuresManager:
@Component
public class CustomLoginFailuresManager extends LoginFailuresManager {
public CustomLoginFailuresManager(RecaptchaProperties recaptcha) {
super(recaptcha);
}
...
}Set your secret key in application.yml file:
recaptcha.validation.secret-key: <your_secret_key>After adding reCAPTCHA support to form login configuration you can only add AuthenticationSuccessHandler that extends
LoginFailuresClearingHandler and AuthenticationFailureHandler that extends LoginFailuresCountingHandler.
There can be 4 different query parameters in redirect to login page:
- error - credentials authentication error
- recaptchaError - reCAPTCHA authentication error
- showRecaptcha - reCAPTCHA must be displayed on login page
- logout - user has been successfully logged out
There is a default LoginFailuresManager implementation in the starter which is InMemoryLoginFailuresManager.
It is recommended to create your own LoginFailuresManager implementation that persists login failures in some storage.
Enable testing mode:
recaptcha.testing.enabled: trueConfigure testing mode:
recaptcha.testing:
success-result: false
result-error-codes: INVALID_SECRET_KEY, INVALID_USER_CAPTCHA_RESPONSEIn testing mode no remote reCAPTCHA validation is fired, the validation process is offline.
recaptcha:
validation:
secret-key: # reCAPTCHA secret key.
response-parameter: g-recaptcha-response # HTTP request parameter name containing user reCAPTCHA response.
verification-url: https://www.google.com/recaptcha/api/siteverify # reCAPTCHA validation endpoint.
timeout:
connect: 500ms # reCAPTCHA validation request connect timeout.
read: 1000ms # reCAPTCHA validation request read timeout.
write: 1000ms # reCAPTCHA validation request write timeout.
security:
failure-url: /login # URL to redirect to when user authentication fails.
login-failures-threshold: 5 # Number of allowed login failures before reCAPTCHA must be displayed.
continue-on-validation-http-error: true # Permits or denies continuing user authentication process after reCAPTCHA validation fails because of HTTP error.
testing:
enabled: false # Flag for enabling and disabling testing mode.
success-result: true # Defines successful or unsuccessful validation result, can be changed during tests.
result-error-codes: # Errors in validation result, can be changed during tests.Go to reCAPTCHA Spring Boot Starter samples to view example applications.
reCAPTCHA Spring Boot Starter is published under Apache License 2.0.