Spring Security, end to end

1. Big picture

Spring Security is a chain of filters that runs before your controller. It does three jobs: confirms who the caller is (authentication), checks what they may do (authorization), and protects against common web attacks (exploit protection).

Mental model in one line: A request arrives → filters read the credentials (password, session cookie or token) and build an Authentication object → it is stored in the SecurityContext → the last filter checks the rules → the request reaches the controller, or gets 401 or 403.

Three questions for every request:

Two basic truths behind everything:

1. HTTP is stateless. The server has no memory, so every request must carry proof (a session cookie or a token).
2. Authentication and authorization are separate questions. First find out who the caller is, then check permissions.

Version note: This guide covers Spring Security 6.x (Boot 3.x) and 7.x (Boot 4.x). This project runs Spring Boot 3.5.5 with Spring Security 6.5 and Spring Authorization Server 1.5.

Mind map

2. Architecture: how a request flows

Spring Security is built entirely on Servlet Filters. Filters run before the DispatcherServlet, so security happens without your controller code knowing.

Layers, outside to inside:

1. Tomcat filter chain: the normal filters in the servlet container.
2. DelegatingFilterProxy: Tomcat does not know about Spring beans. This proxy registers as a Tomcat filter and hands the work to the Spring bean springSecurityFilterChain.
3. FilterChainProxy: that bean. It holds every SecurityFilterChain in your app and picks the first chain that matches the request. It clears the SecurityContext after the request and rejects malformed URLs (such as .. or encoded slashes) through the HttpFirewall.
4. SecurityFilterChain: an ordered list of security filters, built from your HttpSecurity config.
5. DispatcherServlet → Controller: reached only if every filter passes.

Default filters in order, and the job of each (which ones are present depends on your config):

The pattern to remember: first load the context, then protection (headers, CORS, CSRF), then authentication filters (each logs in if it sees its credentials, otherwise passes the request on), and last exception translation + authorization.

Adding your own filter: http.addFilterBefore(myFilter, AuthorizationFilter.class) (or addFilterAfter / addFilterAt). Extend OncePerRequestFilter. Do not make it a @Component, or Boot also registers it with Tomcat and it runs twice.

See the real list: in a lab, use @EnableWebSecurity(debug = true) or logging.level.org.springframework.security=TRACE (the authorization server in this project already logs at trace).

3. Configuration

You define all your security in one or more SecurityFilterChain beans using the HttpSecurity DSL.

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
class SecurityConfig {

  @Bean
  SecurityFilterChain api(HttpSecurity http) throws Exception {
    http
      .securityMatcher("/api/**")                       // which URLs this chain handles
      .authorizeHttpRequests(a -> a
          .requestMatchers("/api/public/**").permitAll()
          .requestMatchers(HttpMethod.DELETE, "/api/**").hasRole("ADMIN")
          .anyRequest().authenticated())                 // anyRequest always last
      .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
      .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
      .csrf(c -> c.disable())                            // only for stateless token APIs
      .cors(Customizer.withDefaults());
    return http.build();
  }

  @Bean
  PasswordEncoder passwordEncoder() {
    return PasswordEncoderFactories.createDelegatingPasswordEncoder();
  }
}

What Spring Boot gives you with no config: every URL requires authentication; form login + HTTP Basic; a user with a random password printed in the log; CSRF on; security headers on; default login and logout pages. Defining your own SecurityFilterChain bean turns off Boot's default chain; defining a UserDetailsService or AuthenticationProvider bean removes the generated user.

Multiple chains: give each chain a securityMatcher and an @Order. FilterChainProxy runs only the first matching chain. A common setup: a stateless JWT chain for /api/**, a separate chain for /actuator/**, and a form-login chain for everything else (no matcher, last in order). If a chain without a matcher is not last, startup fails.

Rule order: rules inside authorizeHttpRequests are checked top to bottom and the first match wins. Put specific rules first and the general one (anyRequest) last.

Version differences (useful when reading old code):

For Security 7 (Boot 4), read the official migration guide. Fixing the deprecation warnings on 6.x makes the move to 7 much easier.

4. Authentication

Authentication proves who the caller is. Every login style in Spring (form, basic, JWT, OAuth2) follows the same pattern: a filter reads the credentials → builds an unauthenticated Authentication → passes it to the AuthenticationManager → if an authenticated Authentication comes back, stores it in the context.

4.1 The Authentication object

Common types: UsernamePasswordAuthenticationToken, JwtAuthenticationToken, OAuth2AuthenticationToken, AnonymousAuthenticationToken, RememberMeAuthenticationToken.

4.2 The engine

1. AuthenticationManager: an interface with one method, authenticate().
2. ProviderManager: the main implementation. It holds a list of AuthenticationProviders, asks each one whether it supports this token type, and hands the token to the first one that does. If none supports it, it throws ProviderNotFoundException. If it has a parent manager, it falls back to that.
3. AuthenticationProvider: does the actual check. Examples: DaoAuthenticationProvider (username/password), JwtAuthenticationProvider, OidcAuthorizationCodeAuthenticationProvider, or your own provider (LDAP, OTP, API key).
4. DaoAuthenticationProvider steps: UserDetailsService.loadUserByUsername() → account checks (locked, disabled, expired) → PasswordEncoder.matches() → credentials-expired check → a successful token with authorities.

4.3 UserDetails and UserDetailsService

UserDetails is your user in a shape Spring understands: username, password hash, authorities, isEnabled, isAccountNonLocked, isAccountNonExpired, isCredentialsNonExpired. UserDetailsService takes a username and returns UserDetails (from JPA, JDBC, LDAP or memory). If the user does not exist, throw UsernameNotFoundException; Spring hides it as "Bad credentials" to stop user enumeration.

4.4 Passwords

• Never store plain text or reversible encryption. Use only a slow, salted, one-way hash.
• BCrypt is the default (strength 10). Argon2, SCrypt and PBKDF2 are also available. The slowness is the point: it makes guessing expensive for an attacker.
• DelegatingPasswordEncoder: the hash carries a prefix such as {bcrypt}, {argon2} or {noop}. Changing algorithms does not break old users, and UserDetailsPasswordService can upgrade a hash automatically at login.
• The same password gives a different hash every time (random salt); matches() still compares correctly.
• Cost: one BCrypt check takes about 50–100 ms. That is why checking a password on every request (HTTP Basic) is bad under high traffic; log in once, then use a session or token.
• In this project, User.withDefaultPasswordEncoder() and {noop} client secrets are fine for a demo, but never for production.

4.5 Login styles

Custom JSON login endpoint (for an SPA): call authenticationManager.authenticate(...), set the context, and call securityContextRepository.saveContext(context, req, res). Without that, the user is anonymous on the next request (a Security 6 change).

4.6 After login, and logout

• Success: AuthenticationSuccessHandler (default: redirect to the saved request). For REST, write a custom handler that returns JSON.
• Failure: AuthenticationFailureHandler (default: /login?error).
• Events: AuthenticationSuccessEvent and subclasses of AbstractAuthenticationFailureEvent are published. Use @EventListener for audit logs, failed-login counters and alerts.
• Account lockout / brute force: not built in. Use failure events + a counter + isAccountNonLocked, or rate limiting at the gateway.
• Logout: POST /logout (with a token when CSRF is on). LogoutFilter invalidates the session, clears the context, deletes cookies (deleteCookies) and clears remember-me. A JWT is stateless, so logout does not kill it (section 9).

5. SecurityContext: where the logged-in user lives

A SecurityContext holds one Authentication. The SecurityContextHolder holds the context, by default in a ThreadLocal, so only the thread handling the request can see it.

Authentication auth = SecurityContextHolder.getContext().getAuthentication();
String user = auth.getName();   // for a JWT this is the "sub" claim

Service B does exactly this in PaymentServiceImpl to find the payment owner. In a controller you can inject it directly: @AuthenticationPrincipal UserDetails user, @AuthenticationPrincipal Jwt jwt, or a Principal principal parameter.

Lifecycle per request:

1. SecurityContextHolderFilter loads the context from the SecurityContextRepository (for sessions, the SPRING_SECURITY_CONTEXT attribute in the HttpSession).
2. On a new login, the authentication filters set the context and save it to the repository.
3. After the request the holder is cleared, so a reused pool thread never leaks a user.

Repositories: HttpSessionSecurityContextRepository (sessions), RequestAttributeSecurityContextRepository (current request only, stateless), DelegatingSecurityContextRepository (both). With stateless JWT, the context is rebuilt from the token on every request and nothing is saved.

Holder strategies:

Threads and async (where real bugs happen):

• @Async, CompletableFuture.supplyAsync() and ExecutorService do not carry the context, so the user is null.
• Fix: wrap the executor with DelegatingSecurityContextAsyncTaskExecutor / DelegatingSecurityContextExecutorService, or use DelegatingSecurityContextRunnable.
• Spring MVC Callable / DeferredResult are handled by WebAsyncManagerIntegrationFilter.
• @Scheduled jobs and Kafka listeners have no HTTP request, so there is no user. That is why the settlement job uses AuthorizedClientServiceOAuth2AuthorizedClientManager: the default manager needs an HTTP request.
• With virtual threads (Java 21), the per-request ThreadLocal still works.

The anonymous user trap: when nobody is logged in, getAuthentication() is not null. It is an AnonymousAuthenticationToken with ROLE_ANONYMOUS, and isAuthenticated() returns true. To check whether someone is really logged in, use AuthenticationTrustResolver.isAnonymous(auth) or check the type.

6. Sessions

With session-based login, the server remembers the user in memory (the session) and the browser sends a JSESSIONID cookie. It is simple and easy to revoke, but the server becomes stateful. In this project only the auth server login page uses a session; Services A, B and Notification are STATELESS.

Creation policy (sessionManagement().sessionCreationPolicy(...)):

Session fixation protection: an attacker gives the victim a known session id; if the victim logs in with it, the attacker gets in too. The fix is a new session id after login (default changeSessionId). Other options: migrateSession, newSession, none (never use).

Concurrent sessions: maximumSessions(1) makes a new login expire the old session; maxSessionsPreventsLogin(true) blocks the new login instead. You need an HttpSessionEventPublisher bean, or expired sessions stay in the count. In a cluster, the SessionRegistry must be shared (Spring Session).

Timeout: server.servlet.session.timeout=30m. When it expires, the user goes to invalidSessionUrl or gets 401. An absolute timeout (a maximum time even while active) is not built in; build it yourself.

Cookie settings: server.servlet.session.cookie.http-only=true (JavaScript cannot read it), secure=true (HTTPS only), same-site=lax or strict (reduces CSRF risk).

Scaling to multiple servers: an in-memory session lives on one server. If the load balancer sends the user to another server, they are logged out. Options: sticky sessions (simple, but sessions are lost when a server dies), Spring Session + Redis or JDBC (shared; recommended), or stateless tokens. This is the stateful vs stateless trade-off from the backend communication course.

7. Authorization

Authorization answers "is this caller allowed to do this?" It works at three levels: URL level (filter), method level (proxy) and object level (is this specific record yours?). Most production bugs happen at the third level.

7.1 Authorities vs roles

• A GrantedAuthority is one permission string, for example orders.read or SCOPE_payment.read.
• A role is an authority with the ROLE_ prefix. hasRole("ADMIN") actually checks for ROLE_ADMIN; hasAuthority("ADMIN") checks for exactly ADMIN.
• User.withUsername(..).roles("ADMIN") adds the prefix; authorities("ROLE_ADMIN") uses the string as is.
• Good design: coarse roles (ADMIN, USER) and fine-grained authorities (orders.delete), with roles mapped to authorities. This project uses scopes only: SCOPE_payment.read, SCOPE_payment.write, SCOPE_notification.send.

7.2 URL authorization

.authorizeHttpRequests(a -> a
    .requestMatchers("/actuator/health", "/error").permitAll()
    .requestMatchers(HttpMethod.POST, "/payments/**").hasAuthority("SCOPE_payment.write")
    .requestMatchers(HttpMethod.GET, "/payments/**").hasAuthority("SCOPE_payment.read")
    .requestMatchers("/reports/**").access(myAuthorizationManager)
    .anyRequest().authenticated())

Options: permitAll, denyAll, authenticated, anonymous, fullyAuthenticated (not via remember-me), rememberMe, hasRole, hasAnyRole, hasAuthority, hasAnyAuthority, access(AuthorizationManager). Rules run top to bottom and the first match wins. If you do not permit /error, real errors show up as 401. The settlement job uses anyRequest().denyAll() because nobody should call into it.

permitAll() vs web.ignoring(): with permitAll the chain still runs (headers, context, CSRF); ignoring skips security entirely. Almost always use permitAll.

7.3 Method security

Turn it on with @EnableMethodSecurity.

SpEL can call a bean: @PreAuthorize("@paymentSecurity.isOwner(#paymentId, authentication)"). This keeps complex rules clean.

Proxy limits: because of the Spring AOP proxy, a call from inside the same class (this.method()) skips the check, and private/final methods are not checked. Define meta-annotations (a custom @IsAdmin) to avoid repeating expressions.

Where to put it: in the service layer, so every entry point (controller, scheduler, Kafka listener) is covered. If it lives only in the controller, another path can bypass it.

7.4 AuthorizationManager

In Security 6, both URL and method checks run on AuthorizationManager<T>: check(authentication, object) returns granted or denied. Write a custom implementation for tenant checks, time-based rules or feature flags, and plug it in with .access(...) or method security.

7.5 Role hierarchy

A RoleHierarchy bean: RoleHierarchyImpl.fromHierarchy("ROLE_ADMIN > ROLE_MANAGER > ROLE_USER"). ADMIN gets every lower role automatically, so you do not repeat hasAnyRole("ADMIN","USER") in rules.

7.6 Object-level security (IDOR)

If /payments/{id} is protected only by a scope, user A can try B's payment id and read B's data. This is IDOR, a top OWASP risk. Service B solves it by looking up the payment together with the token's sub, and returns 404 instead of 403 so an attacker cannot even learn that the id exists. Ways to fix it:

1. Filter by owner in the query: findByIdAndOwnerId(id, currentUserId).
2. @PreAuthorize("@paymentSecurity.isOwner(#id, authentication)").
3. @PostAuthorize on read methods.
4. Multi-tenant: take the tenant id from the token and apply it in every query (Hibernate filter or row-level security).
5. The Spring Security ACL module: per-object permission tables (heavy; for rare cases).

7.7 401 vs 403 handling

ExceptionTranslationFilter catches the exceptions:

• An AuthenticationException, or access denied for an anonymous user → AuthenticationEntryPoint → 401 (or a redirect to the login page, or a WWW-Authenticate header).
• An AccessDeniedException for an authenticated user → AccessDeniedHandler → 403.

For REST APIs, customise both to return a JSON ProblemDetail. Exceptions thrown inside filters never reach @ControllerAdvice (this project's GlobalExceptionHandler), so handle them here.

8. Exploit protection

Even with correct login and roles, attacks can happen through browser behaviour. Spring turns some protections on by default; others are your job.

8.1 CSRF (Cross-Site Request Forgery)

Problem: browsers send cookies automatically. While a user is logged in to your bank, an evil site can submit a hidden form to POST /transfer; the browser attaches the session cookie and the server thinks the request is real.

Fix: state-changing requests (POST, PUT, PATCH, DELETE) must carry a CSRF token that the evil site cannot read. CsrfFilter checks it; missing or wrong means 403.

• Server-rendered forms: Thymeleaf adds the hidden _csrf field automatically.
• SPA: CookieCsrfTokenRepository.withHttpOnlyFalse(); JavaScript reads the cookie and sends it in the X-XSRF-TOKEN header. Because Security 6 masks tokens (BREACH protection), an SPA also needs request-handler config; check your version's docs.
• When you may disable it: when authentication is only a token in the Authorization header (browsers never attach it automatically) and no cookies are used. That is why Services A, B and Notification disable CSRF. If you put a JWT in a cookie, you need CSRF again.
• SameSite=Lax/Strict cookies are an extra layer, not a replacement.
• Common confusion: "GET works, POST returns 403" is almost always CSRF.

8.2 CORS (Cross-Origin Resource Sharing)

This is not server security. It is a browser rule: when JavaScript on app.com calls api.com, the browser first asks api.com whether it allows that (a preflight OPTIONS request). CORS does not apply to curl, Postman, PowerShell or server-to-server calls.

• http.cors(Customizer.withDefaults()) + a CorsConfigurationSource bean: allowed origins, methods, headers and credentials.
• Without http.cors(), the preflight fails in the security filters with 401/403.
• allowCredentials(true) cannot be combined with origin *; use exact origins or allowedOriginPatterns.
• Do not treat CORS as protection for your API; authentication is the protection.

8.3 Security headers (on by default)

8.4 HTTPS and proxies

• Without HTTPS, passwords, cookies and tokens travel as plain text. Always use HTTPS in production.
• TLS usually ends at a load balancer or Nginx, and the app receives HTTP. If the app does not know the original request was HTTPS, redirects, OAuth2 redirect_uri and secure cookies break. Fix: server.forward-headers-strategy=native (or framework), have the proxy set X-Forwarded-Proto/Host, and trust only your own proxy.

8.5 What Spring Security does not do (your job)

• Rate limiting / brute-force protection (Bucket4j, gateway, WAF).
• Input validation (@Valid, as PaymentController does) and SQL injection prevention (JPA parameters, never string concatenation).
• XSS output encoding (Thymeleaf and React escape by default; avoid raw HTML).
• Secrets management (Vault, environment variables, cloud secret managers). The Notification Service already reads Gmail credentials from environment variables.
• Audit logging (build it from the events).
• Dependency patching (CVE scans).

9. JWT and resource server (stateless)

In a stateless setup the server does not remember the user. Every request brings a signed token; the server verifies the signature and trusts the information inside. In Spring, the side that verifies tokens is the resource server. Services A, B and Notification are all resource servers.

9.1 JWT anatomy

header.payload.signature, each part Base64URL-encoded.

• Header: alg (RS256, ES256, HS256) and kid (which key signed it).
• Payload (claims): iss (issuer), sub (user), aud (which client or service it is for), exp (expiry), iat, nbf, scope, and custom claims (roles, tenant_id).
• Signature: made with the issuer's private key. Anyone can read the payload (it is not encrypted), but nobody can change it. Never put passwords or personal data in a JWT.

9.2 Resource server setup

spring.security.oauth2.resourceserver.jwt:
  issuer-uri: http://localhost:9000
  audiences: payment-client          # optional, see 9.3

http.oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()));

What happens on every request: BearerTokenAuthenticationFilter takes the token from the header → JwtDecoder checks the signature (JWKS public key), exp/nbf (with 60 s clock skew), iss, and aud if configured → JwtAuthenticationConverter turns claims into authorities → a JwtAuthenticationToken goes into the context.

On failure: 401 + WWW-Authenticate: Bearer error="invalid_token".

9.3 Claims to authorities, and the audience

• Default: only the scope/scp claim becomes SCOPE_xxx authorities. That is what this project's rules use.
• Keycloak roles (realm_access.roles), Azure AD roles and custom roles claims are not mapped automatically. Write a custom JwtAuthenticationConverter / JwtGrantedAuthoritiesConverter that adds the ROLE_ prefix. When hasRole does not work, this is the cause 90% of the time.
• Audience is not checked by default. Spring Authorization Server puts the requesting client's id in aud. Setting audiences lets a service accept tokens only from the clients you expect (for example, Notification only from payment-service-b).

9.4 Keys and rotation

• Asymmetric (RS256/ES256): the auth server signs with a private key; services verify with the public key from the JWKS URL. Services cannot create tokens. Recommended, and what this project uses.
• Symmetric (HS256): a shared secret. Every service holding the secret can forge tokens. Use it only within a single app.
• JWKS keys are cached. When a token arrives with an unknown kid, Spring fetches the JWKS again, so key rotation needs no restart.
• In the dev profile the auth server generates a new RSA key on every start, so old tokens die on restart; other profiles load a fixed key from a PKCS12 keystore.
• With issuer-uri, the decoder is built lazily: the app starts even if the auth server is down, and fails on the first request.

9.5 The revocation problem

A JWT stays valid until exp. Logout, a password change or disabling the user does not stop it. This project keeps access tokens to 5 minutes. Options:

9.6 Where should a browser keep tokens?

• localStorage: JavaScript injected through XSS can steal it.
• An in-memory JavaScript variable: lost on refresh; lower XSS risk, but not zero.
• An HttpOnly cookie: JavaScript cannot read it, but you need CSRF protection.
• BFF (Backend-for-Frontend) pattern: tokens live only on the server (gateway); the browser holds only a session cookie. The current best practice for SPAs.

9.7 Do not build your own token server casually

Signing JWTs in your own login endpoint works for small apps, but then you maintain key rotation, refresh, revocation and MFA yourself. Use Keycloak, Okta, Auth0, Azure AD or Spring Authorization Server (as this project does). If you do write a custom JWT filter, place it before AuthorizationFilter and send its exceptions to the entry point; the built-in oauth2ResourceServer is the better option.

10. OAuth2 and OpenID Connect

OAuth2 is authorization (delegated access): "let this app access my data on my behalf." OIDC is OAuth2 plus identity: "tell me who this user is" (it adds the ID token). "Login with Google" is OIDC.

10.1 Four roles

10.2 Tokens

• Access token: used to call APIs; read by the resource server. Short-lived.
• Refresh token: used to get a new access token. Long-lived; the client keeps it secret.
• ID token (OIDC): for the client only, carries user info (a JWT). Never send it to APIs.

10.3 Grant types (flows)

Authorization code flow, step by step: the browser hits the client → the client redirects to the auth server (client_id, redirect_uri, scope, state, PKCE code_challenge) → the user logs in and consents → the auth server redirects back to redirect_uri with a code → the client exchanges the code plus its secret/verifier for tokens over a back channel. state prevents CSRF; PKCE makes a stolen code useless.

10.4 Spring's three OAuth2 modules

1. oauth2Login() (client, user login): the flow starts at /oauth2/authorization/{registrationId} and the callback is /login/oauth2/code/{id}. The result is an OAuth2User / OidcUser principal saved in the session. Map roles with a GrantedAuthoritiesMapper or a custom OidcUserService.
2. oauth2Client() (client, calling APIs): OAuth2AuthorizedClientManager gets, caches and refreshes tokens. RestClient/WebClient interceptors add the Bearer header automatically. Client credentials live here (see the settlement job's OAuth2ClientConfig).
3. oauth2ResourceServer() (API side): see section 9.

Plus Spring Authorization Server, if you want to run your own auth server. In this project its chain has @Order(1) and matches only the OAuth2 endpoints; the form-login chain is @Order(2) for everything else.

10.5 Config example (client credentials)

spring.security.oauth2.client:
  registration.settlement-job:
    provider: payment-auth
    client-id: settlement-job
    client-secret: ${SETTLEMENT_SECRET}
    authorization-grant-type: client_credentials
    scope: payment.read,payment.settle
  provider.payment-auth:
    token-uri: http://localhost:9000/oauth2/token

Common production issues: redirect_uri mismatch (http vs https behind a proxy), state not found (session lost on another node), clock skew, wrong scopes, client secret rotation.

11. Microservices security

Zero trust: do not trust the internal network. Every service verifies every call, so one compromised service does not open up the rest. Service B re-validates every token instead of trusting Service A.

11.1 Typical architecture

1. Browser/mobile → API gateway (Spring Cloud Gateway, Nginx or a cloud gateway): user login (OIDC), rate limiting, CORS, TLS. With a BFF, tokens live here.
2. Gateway → services: forwards the user's access token (token relay, as Service A does), or a narrower token the gateway exchanged for.
3. Service → service: token relay or exchange when the user's context is needed; client credentials for background and system calls (Service B → Notification, settlement job → Service B).
4. Every service is a resource server: do not skip checks because the gateway already checked. Verify signature, iss, aud and scope in every service.

11.2 Service-to-service options

A common production combination: mesh mTLS for transport + JWT for app-level authorization.

11.3 Rules that prevent real incidents

• Check the audience in every service. A token issued for one client must not work everywhere.
• Least-privilege scopes for every client (payment-service-b only has notification.send).
• The auth server is a critical dependency: run it highly available and monitor it. Client credentials tokens are cached, so a short outage is tolerated; a long one is not.
• Never pass user identity in a plain header (X-User-Id) without a signature; another service can fake it.
• Async (Kafka) messages: there is no HTTP token. Put the user id and producer identity in the message and authorize on the consumer side; use signed claims for sensitive data.
• Secrets: keep client secrets in a vault or environment variables, with a rotation plan.

11.4 Spring pieces

• Calling side: spring-boot-starter-oauth2-client + OAuth2AuthorizedClientManager + a RestClient/WebClient interceptor (client credentials or relay).
• Receiving side: spring-boot-starter-oauth2-resource-server + audience and scope rules.
• Gateway: the Spring Cloud Gateway TokenRelay filter.

12. Reactive (WebFlux) security

Same concepts, different plumbing. In WebFlux one request does not stay on one thread, so ThreadLocal does not work.

Getting the user: ReactiveSecurityContextHolder.getContext().map(ctx -> ctx.getAuthentication()). Spring Cloud Gateway is reactive, so gateway security is written in this style.

13. Testing security

A security rule without a test is an assumption. Test both the allowed case and the denied case for every rule.

@Test
void readScopeCannotCreatePayment() throws Exception {
  mvc.perform(post("/payments").contentType(APPLICATION_JSON).content(body)
         .with(jwt().authorities(new SimpleGrantedAuthority("SCOPE_payment.read"))))
     .andExpect(status().isForbidden());
}

@Test
void noTokenGets401() throws Exception {
  mvc.perform(get("/payments/1")).andExpect(status().isUnauthorized());
}

Test slices: in @WebMvcTest, confirm your SecurityConfig is actually loaded (add @Import(SecurityConfig.class) if needed); otherwise the tests check Boot's default security, not your rules. For method security, call the service bean directly in a @SpringBootTest.

Checklist per endpoint: anonymous → 401 · wrong scope → 403 · right scope → 200 · another user's object → 404 here (403 elsewhere) · POST without CSRF (session apps) → 403 · expired or tampered token → 401. This project's scripts/test-all.ps1 runs these checks end to end with real tokens.

14. Production

Logging: in development, logging.level.org.springframework.security=TRACE shows what each filter decided. In production use INFO/WARN. Never log passwords, Authorization headers, tokens or session ids, and check your Nginx/Tomcat access log formats too.

Audit: authentication success and failure events, authorization denied events (AuthorizationDeniedEvent, once you enable the publisher), and admin actions. Record who, what, when and from where (IP).

Monitoring: 401/403 rate, login failure rate, token validation errors and auth server latency. Spring Security 6 Micrometer observations show filter chain and authentication timing in traces (this project already samples every trace and prints the trace id in logs). A sudden 401 spike after a deploy usually means a config bug or a key/clock issue.

Actuator: /actuator/health (and info) can be public; env, heapdump, configprops and loggers must never be. Use a separate chain with EndpointRequest.toAnyEndpoint() and an admin role, or keep the management port on the internal network.

Secrets: never put client secrets, DB passwords or signing keys in git. Use environment variables, Vault or a cloud secret manager. If a secret leaks into git, rotate it; deleting the file is not enough.

Patching: Spring Security CVEs come out regularly. Keep Boot patch versions current and run OWASP Dependency-Check, Snyk or Dependabot in CI.

Performance: BCrypt makes the login endpoint the first CPU bottleneck, so rate-limit login. JWT validation is cheap and JWKS is cached. Introspection is a network call on every request, so cache it.

Incident checklist (auth suddenly broken):

1. Are server clocks in sync? (NTP; JWT exp/nbf)
2. Does the issuer URL match exactly? (http vs https, trailing slash, hostname)
3. Behind a proxy: are forwarded headers set and trusted?
4. Can the service reach the JWKS endpoint?
5. Did the audience or scope change?
6. Was a signing key or client secret rotated but not deployed? (In dev, did the auth server restart and invalidate every token?)
7. Is there a new POST endpoint without a CSRF token, or a new frontend origin without CORS?
8. With multiple instances: is the session store shared?
9. Did a dependency upgrade change a default? (read the release notes)

15. Common mistakes

SPRING SECURITY = filters before controller

FLOW: Proxy → FilterChainProxy → Chain
      → AuthN filters → AuthZ filter → Controller

AUTHN (who?)  fail → 401
  Filter → AuthManager → Provider
  → UserDetailsService + PasswordEncoder
  → Authentication in SecurityContext (ThreadLocal)

AUTHZ (allowed?) fail → 403
  URL rules (first match) · @PreAuthorize
  · ownership (IDOR!)

STATE
  Session: JSESSIONID, revocable, needs shared store
  JWT: stateless, verify sig/exp/iss/aud,
       can't revoke → short expiry

PROTECT
  CSRF = cookies (disable only for header tokens)
  CORS = browser only
  Headers on by default · HTTPS + forwarded headers

OAUTH2
  Login: auth code + PKCE · Services: client creds
  Every service = resource server (+ audience)

PROD: test allow+deny · no tokens in logs
      · actuator locked · sync clocks · patch