Spring Security & JWT

The servlet container passes the request to DelegatingFilterProxy/FilterChainProxy (the bean named springSecurityFilterChain), which selects the first SecurityFilterChain whose securityMatcher matches and runs its filters in order. Only if all pass does the request reach DispatcherServlet.

• Typical order: SecurityContextHolderFilter, HeaderWriterFilter, CorsFilter, CsrfFilter, LogoutFilter, authentication filters (UsernamePasswordAuthenticationFilter, BearerTokenAuthenticationFilter), AnonymousAuthenticationFilter, ExceptionTranslationFilter, AuthorizationFilter.
• Debug with logging.level.org.springframework.security=DEBUG or @EnableWebSecurity(debug = true) (dev only).

WebSecurityConfigurerAdapter is removed; declare a SecurityFilterChain bean with the lambda DSL.

@Bean
SecurityFilterChain api(HttpSecurity http) throws Exception {
    return http
        .csrf(csrf -> csrf.disable())
        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .authorizeHttpRequests(a -> a
            .requestMatchers("/actuator/health", "/auth/**").permitAll()
            .requestMatchers("/admin/**").hasRole("ADMIN")
            .anyRequest().authenticated())
        .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
        .build();
}

• authorizeHttpRequests replaces authorizeRequests; requestMatchers replaces antMatchers/mvcMatchers.
• Rules are evaluated in order; first match wins, so put specific before general.

hasRole('ADMIN') checks for authority ROLE_ADMIN. If the granted authority is plain ADMIN, the check fails; use hasAuthority('ADMIN') or add the prefix when mapping.

• A role is just an authority with the ROLE_ prefix by convention; hasRole adds it automatically.
• For JWT, the default JwtGrantedAuthoritiesConverter maps the scope/scp claim to SCOPE_x authorities; a roles claim needs a custom JwtAuthenticationConverter (setAuthoritiesClaimName, setAuthorityPrefix("ROLE_")).
• Method security with @EnableMethodSecurity must be on, otherwise annotations are silently ignored.

Authentication establishes who the caller is: an AuthenticationManager (usually ProviderManager) delegates to AuthenticationProviders and returns a populated Authentication stored in the SecurityContext. Authorization decides what that principal may do, evaluated by AuthorizationFilter (URL rules) or method interceptors.

• Failed authentication -> 401 via AuthenticationEntryPoint; authenticated but denied -> 403 via AccessDeniedHandler.
• Anonymous requests have an AnonymousAuthenticationToken, so "authenticated" checks differ from "not null".

Use a slow, salted, adaptive hash: BCryptPasswordEncoder (cost 10-12), Argon2 (Argon2PasswordEncoder) or scrypt/PBKDF2. PasswordEncoderFactories.createDelegatingPasswordEncoder() prefixes hashes ({bcrypt}...) so algorithms can migrate over time.

• {noop} stores plaintext; a DB leak exposes all users. Fast hashes (MD5/SHA-256) can be brute-forced at billions/second.
• Never use an encoder as new BCryptPasswordEncoder() and compare with equals; use matches(raw, encoded).
• Upgrade hashes on login with UserDetailsPasswordService when upgradeEncoding returns true.

Short-lived access token (5-15 min, stateless, sent as Authorization: Bearer) plus a long-lived opaque refresh token (days) stored server-side (hashed) to allow revocation and rotation.

• On refresh, issue a new access token and rotate the refresh token; if an old refresh token is reused, treat as theft and revoke the whole family.
• Browser storage: refresh token in an HttpOnly; Secure; SameSite cookie, access token in memory; localStorage exposes tokens to XSS.
• Claims: sub, iss, aud, exp, iat, jti, plus roles/scopes; keep payload small and non-sensitive (JWTs are signed, not encrypted).

Verify signature with a trusted key and a fixed expected algorithm, then check exp, nbf, iss, aud. Skipping any is a vulnerability.

• alg: none and algorithm confusion (HS256 with a public RSA key as the HMAC secret) work against libraries that trust the header's alg; pin the algorithm.
• Missing aud check lets a token for service A be accepted by service B.
• Spring's NimbusJwtDecoder.withJwkSetUri(...)/withPublicKey(...).signatureAlgorithm(RS256) validates the signature, exp and nbf; add JwtValidators.createDefaultWithIssuer(issuer) and an audience validator.
• Allow small clock skew (default 60 s).
• Prefer asymmetric keys (RS256/ES256) so resource servers hold only the public key; HS256 secrets must be at least 256 bits.

Because the server keeps no session, revocation needs state somewhere: keep access tokens short, revoke refresh tokens in the DB, and for immediate invalidation keep a denylist of jti (Redis with TTL equal to the token's remaining life) or a per-user tokenVersion/not-before timestamp checked in a filter or OAuth2TokenValidator.

• A denylist makes each request do a cache lookup; trade-off against pure statelessness.
• Changing a password or role should bump the version so older tokens fail.
• Clearing the token on the client is not revocation.

Add spring-boot-starter-oauth2-resource-server, set the issuer URI so Boot discovers JWKS, and enable oauth2ResourceServer(jwt).

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://idp.example.com/realms/acme

• Boot fetches metadata lazily on first request and caches keys; if the IdP is down at that time, requests fail with 401/500, while jwk-set-uri avoids discovery.
• Map IdP-specific role claims (Keycloak realm_access.roles) with a custom JwtAuthenticationConverter.
• Use opaque token introspection (opaquetoken) when tokens are revocable and not JWTs.

CORS is enforced by browsers, not servers or Postman. The preflight OPTIONS request carries no credentials, so Spring Security rejects it with 401 before Spring MVC's CORS config applies unless CORS is enabled in the security chain.

http.cors(c -> c.configurationSource(req -> {
    var cfg = new CorsConfiguration();
    cfg.setAllowedOrigins(List.of("https://app.example.com"));
    cfg.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
    cfg.setAllowedHeaders(List.of("Authorization", "Content-Type"));
    return cfg;
}));

• allowedOrigins("*") cannot be combined with allowCredentials(true); list origins explicitly (or use origin patterns).
• CORS is not authorization; it just relaxes the browser's same-origin policy.

CSRF attacks exploit browsers automatically attaching credentials (cookies, basic auth). Session-cookie apps need CSRF protection. A bearer-token API where the client sets the Authorization header explicitly is not vulnerable, so CSRF can be disabled.

• Left enabled, state-changing requests (POST/PUT/DELETE) without a CSRF token return 403 even with a valid JWT.
• If the JWT is stored in a cookie and sent automatically, CSRF protection is needed again (or SameSite=Strict plus a custom header check).
• For SPAs with cookie sessions use CookieCsrfTokenRepository.withHttpOnlyFalse() and the Spring Security 6 XorCsrfTokenRequestAttributeHandler / SPA handler.

Frequent mistakes:

• permitAll() on /** or broad patterns placed before restricted rules (first match wins).
• Mismatch between MVC path and matcher: trailing slash or /api/users/ vs /api/users; Spring 6 requestMatchers(String) uses the MVC matcher if Spring MVC is present but servlet-path prefixes require MvcRequestMatcher explicit config.
• Actuator exposed (management.endpoints.web.exposure.include=*) without authentication; /h2-console left on.
• Method security not enabled so @PreAuthorize is ignored.
• Trusting client-provided X-Forwarded-*/user-id headers; IDOR (checking authentication but not ownership).
• Disabling security for tests and shipping it.

@PreAuthorize evaluates a SpEL expression before invocation, @PostAuthorize after (can use returnObject), @PreFilter/@PostFilter filter collections.

@PreAuthorize("hasAuthority('SCOPE_orders.read') or #userId == authentication.name")
public List<Order> byUser(String userId) { ... }

@PostAuthorize("returnObject.owner == authentication.name")
public Order get(long id) { ... }

• They require @EnableMethodSecurity and proxy-based invocation: self-invocation and private methods are not protected.
• @PostAuthorize runs after side effects (updates) happen; use pre checks for writes.
• Method security applies on the service layer too, giving defense in depth beyond URL rules.

In controllers use @AuthenticationPrincipal UserDetails/Jwt or Authentication parameters. The SecurityContext is thread-bound, so new threads (@Async, CompletableFuture, executors) see none unless propagated.

• Wrap executors with DelegatingSecurityContextExecutor/DelegatingSecurityContextAsyncTaskExecutor, or set SecurityContextHolder.MODE_INHERITABLETHREADLOCAL (unreliable with pools).
• With virtual threads and structured concurrency prefer passing the principal explicitly.
• Scheduled jobs have no user; run them under a system identity.

Prefer oauth2ResourceServer().jwt(): it handles parsing, signature and standard claim validation, JWKS, error responses (WWW-Authenticate), and is maintained. Write a custom OncePerRequestFilter only for non-standard needs, and then test it thoroughly.

// extract, validate, then set the context
var auth = new UsernamePasswordAuthenticationToken(user, null, authorities);
SecurityContextHolder.getContext().setAuthentication(auth);
chain.doFilter(request, response);

• Custom filters must register before UsernamePasswordAuthenticationFilter (addFilterBefore), skip public paths, and on invalid tokens let the entry point respond rather than silently continuing as anonymous with partial state.
• Do not declare the filter as a @Component unintentionally, it will also be registered as a servlet filter globally and run twice.

Use spring-security-test helpers.

mvc.perform(get("/admin/stats").with(jwt().authorities(new SimpleGrantedAuthority("ROLE_ADMIN"))))
   .andExpect(status().isOk());

mvc.perform(post("/orders").with(jwt()).with(csrf()).content(json))
   .andExpect(status().isForbidden()); // lacks authority

• @WithMockUser(roles = "ADMIN") sets a context directly, bypassing authentication filters; .with(jwt()) exercises the resource server path.
• Test the negative cases: no token -> 401, wrong role -> 403, other user's resource -> 403/404.
• @WebMvcTest needs your SecurityFilterChain imported (@Import(SecurityConfig.class)) and a JwtDecoder mock bean.

Declare two SecurityFilterChain beans with securityMatcher and @Order: the API chain (/api/**, stateless, bearer JWT, no CSRF) first, and the web chain (everything else, form login, sessions, CSRF) last.

• Without securityMatcher on the first chain, it matches everything and the second never runs.
• Each chain has its own entry point: API returns 401 JSON, web redirects to login.
• Session fixation protection and maximumSessions apply only to the session chain.

Combine rate limiting per IP and per account, progressive delays or lockout (with care for DoS on accounts), MFA, breached-password checks, and uniform error messages that do not reveal whether a username exists.

• Implement via an AuthenticationFailureBadCredentialsEvent listener counting failures in Redis, or a gateway/Bucket4j filter.
• Prevent timing-based user enumeration: DaoAuthenticationProvider hides user-not-found (hideUserNotFoundExceptions=true) and runs a dummy hash match.
• Audit-log auth events (AuthenticationSuccessEvent).

The app does not know the original scheme/host because TLS terminates at the proxy. Enable forwarded-header handling (server.forward-headers-strategy=framework or native), and have the proxy set X-Forwarded-Proto/Host/For and strip any client-supplied values.

• requiresChannel().anyRequest().requiresSecure() and secure cookies (server.servlet.session.cookie.secure=true) rely on correct scheme detection.
• Trusting forwarded headers from any client allows spoofing IPs and hosts; only trust your proxy network (server.tomcat.remoteip.internal-proxies).
• HSTS is added by Spring Security only on HTTPS requests.

For simple inheritance use RoleHierarchy (ROLE_ADMIN > ROLE_MANAGER > ROLE_USER) wired into the method-security expression handler (a RoleHierarchy bean is picked up in Spring Security 6.3+ for authorization). For resource-level rules implement a custom bean referenced in SpEL.

@PreAuthorize("@orderAuth.canView(#id, authentication)")
public Order get(long id) { ... }

• Keep authorization logic in one testable component rather than scattered SpEL strings.
• Permissions as authorities (order:read) scale better than many roles; carry coarse scopes in the token and check ownership in the service.
• Do not put huge permission lists in JWTs; the header size limit (often 8 KB) will be hit.

Possible causes: signing key changed or generated at startup per instance (KeyPairGenerator in a bean, so each pod has a different key and tokens from one pod fail on another), issuer URI changed, clock skew/exp, algorithm change, or audience validator added.

• Keys must come from configuration/secret store or a shared JWKS; rotate by publishing the new key under a new kid while the old remains for the token lifetime.
• Read the WWW-Authenticate header: Spring includes the error (invalid_token, "Jwt expired at...", "signature").
• Enable logging.level.org.springframework.security.oauth2=DEBUG.

DaoAuthenticationProvider calls your UserDetailsService.loadUserByUsername, checks account flags (enabled, locked, expired), and compares the submitted password with the stored hash via the PasswordEncoder. Success yields an authenticated UsernamePasswordAuthenticationToken with authorities.

• Declare a UserDetailsService and PasswordEncoder as beans; Boot wires them into the default AuthenticationManager.
• Throw UsernameNotFoundException for unknown users; the provider converts it to BadCredentialsException to avoid leaking existence.
• If a UserDetailsService bean is defined Boot's generated default password user is not created.

Defaults: X-Content-Type-Options: nosniff, Cache-Control: no-cache, no-store, max-age=0, must-revalidate, X-Frame-Options: DENY, Strict-Transport-Security (HTTPS only), X-XSS-Protection: 0. A Content-Security-Policy is not added by default.

• Add CSP via http.headers(h -> h.contentSecurityPolicy(c -> c.policyDirectives("default-src 'self'"))).
• Default no-store hurts cacheability of authenticated GETs; override per endpoint where safe.
• Allow framing selectively with frameOptions().sameOrigin() (e.g. H2 console in dev only).

Authorization must check ownership or tenant, not just login. Scope the query by principal (findByIdAndOwnerId(id, userId)), or check after load with @PostAuthorize, and return 404 (not 403) for other users' resources to avoid revealing existence.

• Unpredictable IDs (UUIDs) are defense in depth, not authorization.
• Apply the same checks in list endpoints, exports and batch operations.
• Add integration tests that log in as user B and request user A's resources.

Hardcoding or committing the secret to Git, using short guessable strings (HS256 needs at least 32 random bytes), and sharing the same secret across environments let anyone forge tokens.

• Load secrets from a vault/secret manager or environment variables; rotate regularly.
• With HS256 every verifier can also sign; prefer RS256/ES256 for multi-service setups so only the auth service holds the private key.
• Base64-decode the secret consistently on both signing and verifying sides; mismatched encoding gives signature errors.

Authorities embedded in a JWT remain until expiry. Options: short access-token TTL with refresh re-reading roles from the DB, a per-user authVersion claim compared on each request against a cached value, or opaque tokens/introspection with central revocation.

• Session-based apps can expire sessions via SessionRegistry.expireNow().
• For critical permissions (admin actions), re-check against the database instead of trusting token claims.