Document generic AuthenticationFilter class

[merusso]

A generic AuthenticationFilter class was added in #6506 to v5.2, but there still isn't any documentation to explain why or how to use it.

Would it be ideal for a web API that uses a form of username/password authentication using custom headers (Client-ID, Client-Secret)? This feels like a simple use case but one that still appears to require a custom filter.

[MasatoshiTada]

Is there any progress on this issue?👀
I'm wondering what this filter is. It seems any class doesn't call this filter.

[abccbaandy]

2025 now...still no update 😢

I have see @Kehrlann 's spring-security-the-good-parts use this class, but I don't find any document for it.
https://github.com/Kehrlann/spring-security-the-good-parts/blob/main/src/main/java/wf/garnier/spring/security/thegoodparts/RobotAuthenticationFilter.java

And no spring class is extends that class, the famous filter UsernamePasswordAuthenticationFilter is extends AbstractAuthenticationProcessingFilter.

Also these two filter looks almost same, is there any design reason?

[Kehrlann]

Let me think about how to best document this. In the meantime, for those wondering about this class:

The AuthenticationFilter is a user helper class, a commodity abstraction. Similar to AuthorityUtils, in a way. Neither of those are mentioned in the javadoc, and they are seldom[1] used in Spring Security itself.

The AuthenticationFilter is a "backport" to the servlet stack of the AuthenticationWebFilter that was introduced with the reactive stack. It represents the "usual steps" in an authentication flow, and is built by composing building blocks:

1. Check if the request should be processed (requestMatcher)
2. Convert the request object into an Authentication (authenticationConverter)
3. Authenticate (authenticationManager, or authenticationManagerResolver for complex use-cases)
4. Handle authentication result:
   a. Authentication success (authenticationSuccessHandler)
   b. or authentication failure (authenticationFailureHandler)

And that's it! There's actually very little code in the filter, it's mostly stringing the building blocks together, handling errors, saving authentication to the security context, and changing the session id. The user provides 5 functions and they will be correctly wired, instead of writing the same imperative logic.

AbstractAuthenticationProcessingFilter, is different because, as the javadoc mentions, it is meant for browser-based http authentication, and supports, for example, simpler configuration for URL redirects on authentication failures, remember-me services and session management. It is not really designed for, say, machine-to-machine authentication. But mostly ... it's an older abstraction that most of spring security was built on top of (2004!)

Today, I'd very likely go with AuthenticationFilter, unless I want to use the support of AbstractAuthenticationFilterConfigurer.

Hope this is helpful.

---

[1] Since 6.4, there is one filter that uses AuthenticationFilter in the one-time-token login flow, but it is harder to discover because it is a direct instance instead of a subclass (source) . It might be the wrong abstraction in this case, maybe we should have used AbstractAuthenticationProcessingFilter instead.

[merusso]

Really helpful explanation, thanks!