jwt-auth-demo/docs/09-manual-filter-vs-resource-server.md

09 — Manual filter vs built-in resource server

← testing · next: production checklist →

Both are in this repository, behind profiles, secured identically. Run them side by side:

./scripts/run.sh hs256                      # hand-written OncePerRequestFilter
./scripts/run.sh hs256,resourceserver       # oauth2ResourceServer().jwt()

The configuration, side by side

Manual — SecurityConfig:

.addFilterBefore(new JwtAuthenticationFilter(jwtDecoder, revokedTokens, entryPoint),
                 UsernamePasswordAuthenticationFilter.class);

plus ~120 lines of filter, plus the entry point and access-denied handler wired by hand.

Built-in — ResourceServerSecurityConfig:

.oauth2ResourceServer(oauth2 -> oauth2
        .jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthenticationConverter())));

One line. BearerTokenAuthenticationFilter is inserted in the right slot, BearerTokenAuthenticationEntryPoint and BearerTokenAccessDeniedHandler are wired, the JwtDecoder bean is picked up automatically, and the RFC 6750 headers are correct on both 401 and 403.

The chains it produces

Manual (transcript step 19):

… HeaderWriterFilter, JwtAuthenticationFilter, RequestCacheAwareFilter, …

Built-in (transcript step 1):

… HeaderWriterFilter, LogoutFilter, OAuth2ProtectedResourceMetadataFilter,
  BearerTokenAuthenticationFilter, RequestCacheAwareFilter, …

Same slot. The extra OAuth2ProtectedResourceMetadataFilter is Spring Security 7's RFC 9728 support — see doc 11.

What moves when you switch

concern	manual filter	resource server
resolve the header	DefaultBearerTokenResolver (you call it)	built in
decode + verify	jwtDecoder.decode(token) (you call it)	built in
exp/nbf/iss	JwtValidators on the decoder	same decoder, same validators
aud	your validator	your validator
token_type	an if in the filter	an OAuth2TokenValidator
denylist / jti	an if in the filter	an OAuth2TokenValidator
authority mapping	your converter	JwtAuthenticationConverter
401 shape	you wire the entry point	built in
403 shape	you wire the handler	built in

The two custom checks do not disappear — they move onto the decoder. That is the trap in the next section.

The trap: the built-in path has no opinion about your claims

Run the same request against both resource-server profiles:

# 4. REFRESH token presented as an access token.
HTTP 200          hs256,resourceserver           (loose)
HTTP 401          hs256,resourceserver,strict    (validator wired)

Files: loose · strict.

Switching from a hand-written filter to oauth2ResourceServer() silently drops every custom check that lived in the filter, because the framework has never heard of your token_type claim or your denylist. The build still passes. The tests still pass, if they only test the happy path. Move them explicitly:

decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(
        JwtValidators.createDefaultWithIssuer(issuer),
        AudienceValidator.forAudience(audience),
        new AccessTokenTypeValidator()));

JwtValidatorFactory in this repository composes exactly that, and the extras are supplied by an ObjectProvider so both profiles get them.

Note also that a denylist check does not belong in an OAuth2TokenValidator on purity grounds — validators are supposed to be pure functions of the token — but it is where it has to go if you want it on the built-in path. The alternative is an AuthenticationSuccessHandler or a small filter after BearerTokenAuthenticationFilter, which puts you halfway back to the manual approach.

Which to pick

Use the built-in resource server if your tokens are ordinary OAuth 2.0 / OIDC access tokens, especially from a real authorization server. It is less code, it is maintained, and it gets RFC compliance right in places you would not think to (the charset in WWW-Authenticate, RFC 9728 metadata, insufficient_scope on 403).

Write the filter if you need behaviour the framework has no hook for — custom header schemes, a token bound to a device fingerprint, per-request key selection across tenants — or if you are teaching, because the filter is where the flow becomes legible.

What this repository actually recommends: start with the built-in one. If you find yourself adding OAuth2TokenValidators for things that are not claims, that is the signal to switch.

A useful third option for a real system: run Spring Authorization Server as the issuer and consume its tokens with oauth2ResourceServer(). Then neither half of this repository is your code.