Mastering Captcha Authentication in Spring Security: Custom Filter Config Guide

The article shows how to improve the configuration of a captcha authentication filter in Spring Security by creating a custom configurer.

Background

CaptchaAuthenticationFilter mimics UsernamePasswordAuthenticationFilter. Its configuration is normally done by FormLoginConfigurer, which uses FormLoginConfigurer to set up UsernamePasswordAuthenticationFilter.

Attempting to extend AbstractAuthenticationFilterConfigurer directly is not recommended because it is intended for internal use; it can only be added via HttpSecurity.addFilter(Filter) when the filter is registered as a built‑in filter.

Solution

Instead, we extend AbstractHttpConfigurer and create CaptchaAuthenticationFilterConfigurer that configures CaptchaAuthenticationFilter directly.

public final class FormLoginConfigurer<H extends HttpSecurityBuilder<H>> extends AbstractAuthenticationFilterConfigurer<H, FormLoginConfigurer<H>, UsernamePasswordAuthenticationFilter> { ... }

The abstract class definition is shown below.

public abstract class AbstractAuthenticationFilterConfigurer<B extends HttpSecurityBuilder<B>, T extends AbstractAuthenticationFilterConfigurer<B,T,F>, F extends AbstractAuthenticationProcessingFilter> extends AbstractHttpConfigurer<T,B> { ... }

We then define CaptchaAuthenticationFilterConfigurer extending AbstractHttpConfigurer, with fields for the filter, services, handlers, etc., and methods to set parameters, init, and configure.

public class CaptchaAuthenticationFilterConfigurer<H extends HttpSecurityBuilder<H>> extends AbstractHttpConfigurer<CaptchaAuthenticationFilterConfigurer<H>, H> { ... }

In initProvider we obtain CaptchaUserDetailsService and CaptchaService from the Spring IoC container if not explicitly set, then register a CaptchaAuthenticationProvider.

private void initProvider(H http) { ... }

Usage

Finally, the configurer is applied in a SecurityFilterChain bean, disabling CSRF, setting request matchers, and calling .apply(new CaptchaAuthenticationFilterConfigurer<>()) with captchaService, captchaUserDetailsService, and a successHandler that writes the authentication object as JSON.

@Bean
SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http, UserDetailsService userDetailsService) throws Exception {
    http.csrf().disable()
        .authorizeRequests()
        .mvcMatchers("/foo/**").access("hasAuthority('ROLE_USER')")
        .anyRequest().authenticated()
        .and()
        .apply(new CaptchaAuthenticationFilterConfigurer<>())
        .captchaService((phone, rawCode) -> true)
        .captchaUserDetailsService(phone -> userDetailsService.loadUserByUsername("felord"))
        .successHandler((request, response, authentication) -> {
            ServletServerHttpResponse servletServerHttpResponse = new ServletServerHttpResponse(response);
            MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
            converter.write(authentication, MediaType.APPLICATION_JSON, servletServerHttpResponse);
        });
    return http.build();
}

The article concludes that mimicking Spring’s internal configurers provides a clean way to integrate captcha authentication without dealing with low‑level filter registration complexities.