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 'com.github.mkopylec:recaptcha-spring-boot-starter:1.3.5'
}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;
@RequestMapping(value = "/", method = POST)
public void validateCaptcha(HttpServletRequest request) {
ValidationResult result = recaptchaValidator.validate(request);
if (result.isSuccess()) {
...
}
}
}Set your secret key in application.yml file:
recaptcha.validation.secretKey: <your_secret_key>RecaptchaValidator provides couple of useful methods to validate reCAPTCHA response.
Add Spring Security dependency:
dependencies {
compile 'org.springframework.boot:spring-boot-starter-security:1.3.2.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
@EnableConfigurationProperties(RecaptchaProperties.class)
public class CustomLoginFailuresManager extends LoginFailuresManager {
@Autowired
public CustomLoginFailuresManager(RecaptchaProperties recaptcha) {
super(recaptcha);
}
...
}Set your secret key in application.yml file:
recaptcha.validation.secretKey: <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 strongly recommended to create your own LoginFailuresManager implementation and not to use the default one.
Enable testing mode:
recaptcha.testing.enabled: trueConfigure testing mode:
recaptcha.testing:
successResult: false
resultErrorCodes: INVALID_SECRET_KEY, INVALID_USER_CAPTCHA_RESPONSEIn testing mode no remote reCAPTCHA validation is fired, the validation process is offline.
recaptcha:
validation:
secretKey: # reCAPTCHA secret key.
responseParameter: g-recaptcha-response # HTTP request parameter name containing user reCAPTCHA response.
verificationUrl: https://www.google.com/recaptcha/api/siteverify # reCAPTCHA validation endpoint.
security:
failureUrl: /login # URL to redirect to when user authentication fails.
loginFailuresThreshold: 5 # Number of allowed login failures before reCAPTCHA must be displayed.
continueOnValidationHttpError: true # Permits on denies continuing user authentication process after reCAPTCHA validation fails because of HTTP error.
testing:
enabled: false # Flag for enabling and disabling testing mode.
successResult: true # Defines successful or unsuccessful validation result, can be changed during tests.
resultErrorCodes: # 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.