Handle spring security authentication exceptions with @ExceptionHandler

Handling Spring Security Authentication Exceptions with @ExceptionHandler

If you've been working with Spring MVC's @ControllerAdvice and @ExceptionHandler, you might have encountered a common problem: it works fine for exceptions thrown by web MVC controllers, but not for exceptions thrown by Spring Security custom filters. These filters run before the controller methods are invoked.

One scenario where this problem might arise is when you have a custom Spring Security filter for token-based authentication. Let's take a look at an example:

public class AegisAuthenticationFilter extends GenericFilterBean {
    // ...
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException {
        try {
            // ...
        } catch(AuthenticationException authenticationException) {
            SecurityContextHolder.clearContext();
            authenticationEntryPoint.commence(request, response, authenticationException);
        }
    }
}

@Component("restAuthenticationEntryPoint")
public class RestAuthenticationEntryPoint implements AuthenticationEntryPoint {
    public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authenticationException) throws IOException, ServletException {
        response.sendError(HttpServletResponse.SC_UNAUTHORIZED, authenticationException.getMessage());
    }
}

@ControllerAdvice
public class RestEntityResponseExceptionHandler extends ResponseEntityExceptionHandler {
    @ExceptionHandler({ InvalidTokenException.class, AuthenticationException.class })
    @ResponseStatus(value = HttpStatus.UNAUTHORIZED)
    @ResponseBody
    public RestError handleAuthenticationException(Exception ex) {
        int errorCode = AegisErrorCode.GenericAuthenticationError;
        if(ex instanceof AegisException) {
            errorCode = ((AegisException)ex).getCode();
        }
        RestError re = new RestError(
            HttpStatus.UNAUTHORIZED,
            errorCode, 
            "...",
            ex.getMessage());
        return re;
    }
}

In this example, we have a custom Spring Security filter (AegisAuthenticationFilter) and an authentication entry point (RestAuthenticationEntryPoint). We also have a ControllerAdvice class (RestEntityResponseExceptionHandler) to handle exceptions globally.

The issue here is that when an AuthenticationException is thrown in the AegisAuthenticationFilter, it is caught and forwarded to the RestAuthenticationEntryPoint, which then sends an unauthorized error response. However, this response does not go through the @ExceptionHandler in the RestEntityResponseExceptionHandler, which means we cannot return a detailed JSON body for the AuthenticationException.

To make the Spring Security AuthenticationEntryPoint and Spring MVC @ExceptionHandler work together, we can use a simple solution:

1. Create a custom exception class, let's call it CustomAuthenticationException, that extends AuthenticationException.

   public class CustomAuthenticationException extends AuthenticationException { public CustomAuthenticationException(String message) { super(message); } }

2. In the AegisAuthenticationFilter, catch the AuthenticationException and rethrow it as CustomAuthenticationException.

   public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException { try { // ... } catch(AuthenticationException authenticationException) { SecurityContextHolder.clearContext(); throw new CustomAuthenticationException(authenticationException.getMessage()); } }

3. Update the RestEntityResponseExceptionHandler to also handle CustomAuthenticationException.

   @ExceptionHandler({ InvalidTokenException.class, AuthenticationException.class, CustomAuthenticationException.class }) @ResponseStatus(value = HttpStatus.UNAUTHORIZED) @ResponseBody public RestError handleAuthenticationException(Exception ex) { // ... }

With these changes, when an AuthenticationException is thrown in the AegisAuthenticationFilter, it will be caught and transformed into a CustomAuthenticationException. This new exception can then be handled by the @ExceptionHandler in the RestEntityResponseExceptionHandler, allowing us to return a detailed JSON body for it.

Remember to update your dependencies if you're using different versions of Spring Security and Spring MVC.

So go ahead and give this solution a try! Handle your Spring Security authentication exceptions with ease, and provide your users with meaningful error responses. If you found this blog post helpful, don't forget to share it with your fellow developers. And if you have any questions or suggestions, feel free to leave a comment below. Happy coding! ✨👩‍💻🚀