Spring Boot Auth Whitelist: AOP, Interceptor, Resolver, and Filter

The article introduces four ways to implement a generic authentication whitelist in a Spring Boot web framework: traditional AOP, Interceptor, ArgumentResolver, and Filter, and provides example code for each.

Traditional AOP

Implementation

Declare an aspect class with @Aspect (e.g., WhitelistAspect).

Add a pointcut method annotated with a custom annotation @Whitelist to mark methods that need whitelist checking.

Use @Before on a advice method (e.g., checkAppkeyWhitelist) to perform the whitelist validation before the controller method executes.

@Aspect
public class WhitelistAspect {
    @Before(value = "whitelistPointcut() && @annotation(whitelist)")
    public void checkAppkeyWhitelist(JoinPoint joinPoint, Whitelist whitelist) {
        checkWhitelist();
        // joinPoint.getArgs() can retrieve method arguments
        // whitelist provides annotation parameters
    }

    @Pointcut("@annotation(com.zhenbianshu.Whitelist)")
    public void whitelistPointCut() { }
}

Extension

The aspect can be extended by adding more annotation attributes (e.g., uid()) or using other pointcut expressions such as execution and notification types like @Around or @After.

Interceptor

Implementation

Define an interceptor class (e.g., WhitelistInterceptor) that implements HandlerInterceptor.

Override preHandle() to retrieve the @Whitelist annotation from the handler method and decide whether to allow the request.

Register the interceptor in a WebMvcConfigurerAdapter implementation.

@Component
public class WhitelistInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        Whitelist whitelist = ((HandlerMethod) handler).getMethodAnnotation(Whitelist.class);
        // use request and whitelist to validate
        return true; // return false to block the request
    }

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        // executed after controller method
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        // executed after view rendering
    }
}

@Configuration
public class MvcConfiguration extends WebMvcConfigurerAdapter {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new WhitelistInterceptor()).addPathPatterns("/*").order(1);
    }
}

Extension

The interceptor must be explicitly enabled via the configuration class; its order determines when it runs relative to other interceptors.

ArgumentResolver

Implementation

Create a custom parameter type (e.g., AuthParam) that holds the appkey information.

Implement HandlerMethodArgumentResolver (e.g., AuthParamResolver) to resolve the custom parameter.

In supportsParameter(), check for the custom type.

In resolveArgument(), retrieve the @Whitelist annotation and validate the appkey, then return an AuthParam instance.

Add the resolver to the MVC configuration.

@Component
public class AuthParamResolver implements HandlerMethodArgumentResolver {
    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.getParameterType().equals(AuthParam.class);
    }

    @Override
    public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
                                  NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
        Whitelist whitelist = parameter.getMethodAnnotation(Whitelist.class);
        // validate whitelist using webRequest and annotation
        return new AuthParam();
    }
}

@Configuration
public class MvcConfiguration extends WebMvcConfigurerAdapter {
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> argumentResolvers) {
        argumentResolvers.add(new AuthParamResolver());
    }
}

Filter

Implementation

Filters are defined by implementing javax.servlet.Filter. They operate outside the Spring container, using raw ServletRequest and ServletResponse objects.

public class WhitelistFilter implements javax.servlet.Filter {
    @Override
    public void init(FilterConfig filterConfig) throws ServletException {
        // called once after initialization
    }

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        // decide whether to block the request
        chain.doFilter(request, response); // must invoke to continue processing
    }

    @Override
    public void destroy() {
        // called once on destroy
    }
}

@Configuration
public class FilterConfiguration {
    @Bean
    public FilterRegistrationBean someFilterRegistration() {
        FilterRegistrationBean registration = new FilterRegistrationBean();
        registration.setFilter(new WhitelistFilter());
        registration.addUrlPatterns("/*");
        registration.setName("whitelistFilter");
        registration.setOrder(1);
        return registration;
    }
}

Summary

The four mechanisms are suitable for different scenarios, and they are invoked in a fixed order during request processing: the Servlet Filter runs first, followed by the Spring Interceptor , then the custom ArgumentResolver , and finally the AOP advice.