Spring Security

Spring Security is that module everyone copies from Stack Overflow without understanding. In interviews, 90% of candidates can't explain how a request gets authenticated end-to-end. They paste a SecurityFilterChain bean, slap @PreAuthorize on a method, and pray it works. Let me take you through it the way I'd explain it to a teammate before their Amazon interview — starting from first principles, building up to production-grade JWT auth, and covering every gotcha I've seen trip up senior engineers.

Authentication vs Authorization

The most confused concept in security interviews. Every candidate says "authentication is who you are, authorization is what you can do" — but few can explain the mechanics.

Think of a bank. Authentication is the teller checking your ID before opening the vault door. Authorization is the vault having different compartments — your key only opens your safe deposit box, not the bank manager's.

SecurityContext & SecurityContextHolder

What it does: Stores the currently authenticated user's info so any code in your application can access it without passing it around as a parameter.

Why it exists: HTTP is stateless. Once a filter authenticates a request, downstream code (controllers, services, repositories) needs to know WHO made the request. Without a centralized holder, you'd pass Authentication objects through every method signature.

How it works internally:

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart LR
    F["🔐 Auth Filter"] -->|"setAuthentication()"| SC["SecurityContext"]
    SC -->|"stored in"| TL["ThreadLocal<br/>(per-request thread)"]
    C["🎯 Controller"] -->|"getAuthentication()"| SC
    S["⚙️ Service"] -->|"getAuthentication()"| SC
    CL["🧹 Cleanup Filter"] -->|"clearContext()"| TL

    style TL fill:#FEF3C7,stroke:#FCD34D,color:#1E40AF
    style SC fill:#EFF6FF,stroke:#DBEAFE,color:#1E40AF

// Anywhere in your code — get the current authenticated user
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
String username = auth.getName();
Collection<? extends GrantedAuthority> authorities = auth.getAuthorities();
Object principal = auth.getPrincipal(); // usually UserDetails

UserDetails & UserDetailsService

What it does: The contract Spring Security uses to load user information from your data store during authentication.

Why it exists: Spring Security doesn't know if your users are in PostgreSQL, MongoDB, LDAP, or an external API. UserDetailsService is the adapter pattern — you implement one method, and Spring Security can authenticate against ANY user store.

public interface UserDetailsService {
    UserDetails loadUserByUsername(String username) throws UsernameNotFoundException;
}

public interface UserDetails extends Serializable {
    Collection<? extends GrantedAuthority> getAuthorities();
    String getPassword();
    String getUsername();
    boolean isAccountNonExpired();
    boolean isAccountNonLocked();
    boolean isCredentialsNonExpired();
    boolean isEnabled();
}

Production implementation for an e-commerce platform:

@Service
@RequiredArgsConstructor
public class EcommerceUserDetailsService implements UserDetailsService {

    private final UserRepository userRepository;

    @Override
    @Transactional(readOnly = true)
    public UserDetails loadUserByUsername(String email) throws UsernameNotFoundException {
        AppUser user = userRepository.findByEmail(email)
            .orElseThrow(() -> new UsernameNotFoundException(
                "No account found with email: " + email));

        if (!user.isEmailVerified()) {
            throw new DisabledException("Email not verified for: " + email);
        }

        return User.builder()
            .username(user.getEmail())
            .password(user.getPasswordHash())  // BCrypt-encoded in DB
            .roles(user.getRoles().stream()
                .map(Role::getName)
                .toArray(String[]::new))
            .accountLocked(user.getFailedLoginAttempts() >= 5)
            .build();
    }
}

PasswordEncoder

What it does: Hashes passwords for storage and verifies passwords during login.

Why it exists: Storing plaintext passwords is criminally negligent. Even encrypted passwords are vulnerable if the encryption key is compromised. Hashing is one-way — even if the database leaks, attackers can't reverse the hashes (with proper algorithms).

@Bean
public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder(12); // cost factor 12 = ~250ms per hash
    // Default is 10 (~100ms). Each increment doubles the time.
    // 12 is sweet spot: fast enough for login, slow enough to deter brute-force
}

Migration strategy (legacy system with MD5 passwords):

@Bean
public PasswordEncoder passwordEncoder() {
    // DelegatingPasswordEncoder supports multiple formats
    // New passwords: {bcrypt}$2a$12$...
    // Legacy passwords: {MD5}5f4dcc3b5aa765d61d8327deb882cf99
    Map<String, PasswordEncoder> encoders = Map.of(
        "bcrypt", new BCryptPasswordEncoder(12),
        "MD5", new MessageDigestPasswordEncoder("MD5")  // deprecated but needed for migration
    );
    DelegatingPasswordEncoder delegate = new DelegatingPasswordEncoder("bcrypt", encoders);
    delegate.setDefaultPasswordEncoderForMatches(new BCryptPasswordEncoder(12));
    return delegate;
}

GrantedAuthority vs Role — The ROLE_ Prefix Confusion

What it does: GrantedAuthority is the interface representing a permission. A Role is just a GrantedAuthority with a ROLE_ prefix convention.

Why the confusion exists: Spring Security has TWO methods — hasRole("ADMIN") and hasAuthority("ROLE_ADMIN") — that do THE SAME THING. The hasRole() method auto-prepends ROLE_. This is legacy design that still trips up experienced developers.

// These are EQUIVALENT:
.requestMatchers("/admin/**").hasRole("ADMIN")        // adds ROLE_ prefix internally
.requestMatchers("/admin/**").hasAuthority("ROLE_ADMIN")  // uses exact string

// This is for fine-grained permissions WITHOUT the prefix:
.requestMatchers("/reports/**").hasAuthority("REPORT_EXPORT")  // no prefix added

The Security Filter Chain — How a Request Gets Authenticated

This is the #1 interview question: "Walk me through what happens when an HTTP request hits a Spring Security-protected endpoint."

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart TD
    REQ["📱 HTTP Request"] --> DFP["DelegatingFilterProxy<br/>(Servlet Container)"]
    DFP --> FCP["FilterChainProxy<br/>(Spring Bean)"]
    FCP --> MATCH{"Match SecurityFilterChain<br/>by request pattern"}
    MATCH --> CORS["1️⃣ CorsFilter"]
    CORS --> CSRF["2️⃣ CsrfFilter"]
    CSRF --> AUTH["3️⃣ Authentication Filter<br/>(JWT / Form / Basic)"]
    AUTH -->|"Creates Authentication object"| CTX["4️⃣ SecurityContextHolder<br/>(stores in ThreadLocal)"]
    CTX --> AUTHZ["5️⃣ AuthorizationFilter<br/>(checks roles/permissions)"]
    AUTHZ -->|"✅ Allowed"| CTRL["🎯 Your Controller"]
    AUTHZ -->|"❌ Denied"| EXH["ExceptionTranslationFilter"]
    EXH -->|"Not authenticated"| R401["401 Unauthorized"]
    EXH -->|"Authenticated but no permission"| R403["403 Forbidden"]

    style REQ fill:#FEF3C7,stroke:#FCD34D,color:#1E40AF
    style AUTH fill:#EFF6FF,stroke:#DBEAFE,color:#1E40AF
    style AUTHZ fill:#ECFDF5,stroke:#6EE7B7,color:#1E40AF
    style R401 fill:#FEE2E2,stroke:#FCA5A5,color:#1E40AF
    style R403 fill:#FEE2E2,stroke:#FCA5A5,color:#1E40AF

The complete filter order (Spring Security 6):

1. ChannelProcessingFilter — Redirects HTTP to HTTPS if required
2. CorsFilter — Handles preflight OPTIONS requests
3. CsrfFilter — Validates CSRF tokens on state-changing requests
4. LogoutFilter — Intercepts /logout URL
5. UsernamePasswordAuthenticationFilter — Form login processing
6. BasicAuthenticationFilter — HTTP Basic header processing
7. BearerTokenAuthenticationFilter — JWT/OAuth2 token processing
8. SecurityContextHolderFilter — Persists SecurityContext between requests
9. ExceptionTranslationFilter — Converts security exceptions to HTTP responses
10. AuthorizationFilter — Final gatekeeper, evaluates access rules

SecurityFilterChain Configuration (Spring Boot 3 / Spring Security 6)

Spring Security 6 removed WebSecurityConfigurerAdapter. If an interviewer's example uses extends WebSecurityConfigurerAdapter, politely mention it's deprecated since Spring Security 5.7 and removed in 6.0. The modern approach is component-based.

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(csrf -> csrf.disable())  // stateless API — no cookies, no CSRF risk
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**", "/actuator/health").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .requestMatchers("/api/orders/**").hasAnyRole("USER", "ADMIN")
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults())
            .build();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(12);
    }
}

// Correct multi-chain configuration
@Bean
@Order(1)  // evaluated first — more specific
public SecurityFilterChain adminChain(HttpSecurity http) throws Exception {
    return http
        .securityMatcher("/admin/**")
        .authorizeHttpRequests(auth -> auth.anyRequest().hasRole("ADMIN"))
        .formLogin(Customizer.withDefaults())
        .build();
}

@Bean
@Order(2)  // evaluated second — broader catch-all
public SecurityFilterChain apiChain(HttpSecurity http) throws Exception {
    return http
        .securityMatcher("/api/**")
        .csrf(csrf -> csrf.disable())
        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)
        .build();
}

Authentication Mechanisms

Form Login (Session-Based)

When to use: Server-rendered web apps (Thymeleaf, JSP), admin dashboards, internal tools.

When NOT to use: SPAs (React/Angular), mobile backends, microservice-to-microservice calls.

@Bean
public SecurityFilterChain formLoginChain(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/login", "/css/**", "/js/**").permitAll()
            .anyRequest().authenticated()
        )
        .formLogin(form -> form
            .loginPage("/login")             // custom login page
            .loginProcessingUrl("/perform-login")  // form action URL
            .defaultSuccessUrl("/dashboard", true)
            .failureUrl("/login?error=true")
            .usernameParameter("email")      // if form field isn't "username"
        )
        .rememberMe(remember -> remember
            .key("uniqueAndSecretKey")
            .tokenValiditySeconds(7 * 24 * 3600)  // 7 days
        )
        .logout(logout -> logout
            .logoutUrl("/perform-logout")
            .logoutSuccessUrl("/login?logout")
            .deleteCookies("JSESSIONID", "remember-me")
        )
        .build();
}

HTTP Basic

When to use: Service-to-service calls within a trusted network, actuator endpoints, quick prototyping.

When NEVER to use: Browser-facing APIs (credentials in every request, no logout mechanism, base64 is NOT encryption).

@Bean
public SecurityFilterChain basicAuthChain(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .httpBasic(Customizer.withDefaults())
        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .build();
}

JWT Authentication — Complete Production Implementation

This is what 80% of Spring Security interviews focus on. Here's a full implementation for an e-commerce platform.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
sequenceDiagram
    participant C as 📱 Client
    participant AC as AuthController
    participant AM as AuthenticationManager
    participant JWT as JwtService
    participant F as JwtAuthFilter
    participant API as 🛒 Order API

    C->>AC: POST /api/auth/login {email, password}
    AC->>AM: authenticate(UsernamePasswordAuthToken)
    AM->>AM: DaoAuthenticationProvider validates
    AM-->>AC: Authentication object (success)
    AC->>JWT: generateToken(userDetails)
    JWT-->>C: {"accessToken": "eyJ...", "expiresIn": 900}

    Note over C,API: Later — accessing protected resource

    C->>F: GET /api/orders<br/>Authorization: Bearer eyJ...
    F->>JWT: extractUsername(token)
    F->>JWT: isTokenValid(token, userDetails)
    JWT-->>F: true
    F->>F: Set SecurityContextHolder
    F->>API: Forward authenticated request
    API-->>C: 200 OK — order data

@Service
public class JwtService {

    @Value("${app.jwt.secret}")
    private String secret;

    @Value("${app.jwt.expiration-ms:900000}")  // 15 minutes default
    private long accessTokenExpiration;

    @Value("${app.jwt.refresh-expiration-ms:604800000}")  // 7 days
    private long refreshTokenExpiration;

    public String generateAccessToken(UserDetails userDetails) {
        Map<String, Object> claims = Map.of(
            "roles", userDetails.getAuthorities().stream()
                .map(GrantedAuthority::getAuthority)
                .toList()
        );
        return buildToken(claims, userDetails.getUsername(), accessTokenExpiration);
    }

    public String generateRefreshToken(UserDetails userDetails) {
        return buildToken(Map.of(), userDetails.getUsername(), refreshTokenExpiration);
    }

    private String buildToken(Map<String, Object> extraClaims, String subject, long expiration) {
        return Jwts.builder()
            .claims(extraClaims)
            .subject(subject)
            .issuedAt(new Date())
            .expiration(new Date(System.currentTimeMillis() + expiration))
            .signWith(getSigningKey())
            .compact();
    }

    public String extractUsername(String token) {
        return extractClaim(token, Claims::getSubject);
    }

    public boolean isTokenValid(String token, UserDetails userDetails) {
        String username = extractUsername(token);
        return username.equals(userDetails.getUsername()) && !isTokenExpired(token);
    }

    private boolean isTokenExpired(String token) {
        return extractClaim(token, Claims::getExpiration).before(new Date());
    }

    private <T> T extractClaim(String token, Function<Claims, T> resolver) {
        Claims claims = Jwts.parser()
            .verifyWith(getSigningKey())
            .build()
            .parseSignedClaims(token)
            .getPayload();
        return resolver.apply(claims);
    }

    private SecretKey getSigningKey() {
        return Keys.hmacShaKeyFor(Decoders.BASE64.decode(secret));
    }
}

@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private static final Logger log = LoggerFactory.getLogger(JwtAuthenticationFilter.class);

    private final JwtService jwtService;
    private final UserDetailsService userDetailsService;

    @Override
    protected void doFilterInternal(HttpServletRequest request,
            HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {

        String header = request.getHeader("Authorization");

        if (header == null || !header.startsWith("Bearer ")) {
            chain.doFilter(request, response);
            return;  // not a JWT request — let other filters handle it
        }

        String token = header.substring(7);

        try {
            String username = jwtService.extractUsername(token);

            // Only authenticate if not already authenticated (idempotency)
            if (username != null &&
                    SecurityContextHolder.getContext().getAuthentication() == null) {

                UserDetails userDetails = userDetailsService.loadUserByUsername(username);

                if (jwtService.isTokenValid(token, userDetails)) {
                    UsernamePasswordAuthenticationToken authToken =
                        new UsernamePasswordAuthenticationToken(
                            userDetails, null, userDetails.getAuthorities());
                    authToken.setDetails(
                        new WebAuthenticationDetailsSource().buildDetails(request));
                    SecurityContextHolder.getContext().setAuthentication(authToken);
                }
            }
        } catch (ExpiredJwtException ex) {
            log.debug("Expired JWT for request: {}", request.getRequestURI());
        } catch (MalformedJwtException | SignatureException ex) {
            log.warn("Invalid JWT: {}", ex.getMessage());
        } catch (Exception ex) {
            log.error("JWT processing failed", ex);
        }

        // ALWAYS continue the filter chain
        // Unauthenticated requests will be rejected by AuthorizationFilter with 401
        chain.doFilter(request, response);
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        // Skip JWT processing for public endpoints (optimization)
        String path = request.getRequestURI();
        return path.startsWith("/api/auth/") || path.startsWith("/actuator/");
    }
}

@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {

    private final AuthenticationManager authenticationManager;
    private final JwtService jwtService;
    private final UserDetailsService userDetailsService;
    private final RefreshTokenService refreshTokenService;

    @PostMapping("/login")
    public ResponseEntity<AuthResponse> login(@Valid @RequestBody LoginRequest request) {
        authenticationManager.authenticate(
            new UsernamePasswordAuthenticationToken(
                request.email(), request.password()));

        UserDetails user = userDetailsService.loadUserByUsername(request.email());
        String accessToken = jwtService.generateAccessToken(user);
        String refreshToken = jwtService.generateRefreshToken(user);

        // Store refresh token server-side for revocation capability
        refreshTokenService.save(user.getUsername(), refreshToken);

        return ResponseEntity.ok(new AuthResponse(accessToken, refreshToken, 900));
    }

    @PostMapping("/refresh")
    public ResponseEntity<AuthResponse> refresh(@RequestBody RefreshRequest request) {
        String refreshToken = request.refreshToken();

        // Validate refresh token exists in DB (not revoked)
        if (!refreshTokenService.isValid(refreshToken)) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
        }

        String username = jwtService.extractUsername(refreshToken);
        UserDetails user = userDetailsService.loadUserByUsername(username);

        if (!jwtService.isTokenValid(refreshToken, user)) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
        }

        // Rotate refresh token (invalidate old, issue new)
        refreshTokenService.revoke(refreshToken);
        String newAccessToken = jwtService.generateAccessToken(user);
        String newRefreshToken = jwtService.generateRefreshToken(user);
        refreshTokenService.save(username, newRefreshToken);

        return ResponseEntity.ok(new AuthResponse(newAccessToken, newRefreshToken, 900));
    }

    @PostMapping("/logout")
    public ResponseEntity<Void> logout(@RequestBody RefreshRequest request) {
        refreshTokenService.revoke(request.refreshToken());
        return ResponseEntity.noContent().build();
    }
}

record LoginRequest(@Email String email, @NotBlank String password) {}
record RefreshRequest(@NotBlank String refreshToken) {}
record AuthResponse(String accessToken, String refreshToken, int expiresInSeconds) {}

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    private final JwtAuthenticationFilter jwtFilter;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(csrf -> csrf.disable())
            .cors(cors -> cors.configurationSource(corsSource()))
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint((req, res, authEx) -> {
                    res.setContentType("application/json");
                    res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
                    res.getWriter().write(
                        """
                        {"error": "unauthorized", "message": "Authentication required"}
                        """);
                })
                .accessDeniedHandler((req, res, accessEx) -> {
                    res.setContentType("application/json");
                    res.setStatus(HttpServletResponse.SC_FORBIDDEN);
                    res.getWriter().write(
                        """
                        {"error": "forbidden", "message": "Insufficient permissions"}
                        """);
                })
            )
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .requestMatchers(HttpMethod.GET, "/api/products/**").permitAll()
                .requestMatchers("/api/orders/**").hasAnyRole("USER", "ADMIN")
                .anyRequest().authenticated()
            )
            .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)
            .build();
    }

    @Bean
    public AuthenticationManager authenticationManager(
            AuthenticationConfiguration config) throws Exception {
        return config.getAuthenticationManager();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(12);
    }

    @Value("${app.cors.allowed-origins}")
    private List<String> allowedOrigins;

    private CorsConfigurationSource corsSource() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOrigins(allowedOrigins);
        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
        config.setAllowedHeaders(List.of("Authorization", "Content-Type"));
        config.setExposedHeaders(List.of("X-Total-Count"));
        config.setAllowCredentials(true);
        config.setMaxAge(3600L);
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/api/**", config);
        return source;
    }
}

OAuth2 / OpenID Connect

When to use: Social login (Google, GitHub), enterprise SSO (Okta, Auth0, Keycloak), when you don't want to manage passwords.

Grant types and when to use each:

// OAuth2 Login — server-side app acting as OAuth2 client
@Bean
public SecurityFilterChain oauth2LoginChain(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .oauth2Login(oauth2 -> oauth2
            .userInfoEndpoint(userInfo -> userInfo
                .userService(customOAuth2UserService())  // map provider claims to your user model
            )
            .successHandler((req, res, auth) -> res.sendRedirect("/dashboard"))
        )
        .build();
}

# application.yml
spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: ${GOOGLE_CLIENT_ID}
            client-secret: ${GOOGLE_CLIENT_SECRET}
            scope: openid, profile, email
          github:
            client-id: ${GITHUB_CLIENT_ID}
            client-secret: ${GITHUB_CLIENT_SECRET}
            scope: user:email

OAuth2 Resource Server (validating external JWTs):

// Your API validates tokens issued by Keycloak/Auth0/Okta
@Bean
public SecurityFilterChain resourceServerChain(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/api/public/**").permitAll()
            .anyRequest().authenticated()
        )
        .oauth2ResourceServer(oauth2 -> oauth2
            .jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthConverter()))
        )
        .build();
}

@Bean
public JwtAuthenticationConverter jwtAuthConverter() {
    JwtGrantedAuthoritiesConverter authoritiesConverter = new JwtGrantedAuthoritiesConverter();
    authoritiesConverter.setAuthorityPrefix("ROLE_");
    authoritiesConverter.setAuthoritiesClaimName("roles");  // custom claim from your IdP

    JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
    converter.setJwtGrantedAuthoritiesConverter(authoritiesConverter);
    return converter;
}

Authorization — URL-Level vs Method-Level

URL-Based (SecurityFilterChain)

Rules are evaluated top-to-bottom. First match wins.

.authorizeHttpRequests(auth -> auth
    // Public endpoints — NO authentication required
    .requestMatchers(HttpMethod.GET, "/api/products/**").permitAll()
    .requestMatchers("/api/auth/**").permitAll()

    // Admin only
    .requestMatchers("/api/admin/**").hasRole("ADMIN")

    // Specific HTTP method + role
    .requestMatchers(HttpMethod.DELETE, "/api/orders/**").hasRole("ADMIN")
    .requestMatchers("/api/orders/**").hasAnyRole("USER", "ADMIN")

    // Fine-grained authority (no ROLE_ prefix)
    .requestMatchers("/api/reports/export").hasAuthority("REPORT_EXPORT")

    // Everything else — must be authenticated (deny by default)
    .anyRequest().authenticated()
)

Method-Level Security

Requires @EnableMethodSecurity on a configuration class. This uses AOP proxies.

@RestController
@RequestMapping("/api/orders")
@RequiredArgsConstructor
public class OrderController {

    private final OrderService orderService;

    @GetMapping
    @PreAuthorize("hasRole('USER')")
    public List<OrderDto> getMyOrders(@AuthenticationPrincipal UserDetails user) {
        return orderService.findByUsername(user.getUsername());
    }

    @GetMapping("/{id}")
    @PreAuthorize("hasRole('ADMIN') or @orderSecurity.isOwner(#id, authentication)")
    public OrderDto getOrder(@PathVariable Long id) {
        return orderService.findById(id);
    }

    @DeleteMapping("/{id}")
    @PreAuthorize("hasRole('ADMIN')")
    public void deleteOrder(@PathVariable Long id) {
        orderService.delete(id);
    }

    @GetMapping("/admin/all")
    @Secured("ROLE_ADMIN")  // simpler — no SpEL, just role strings
    public List<OrderDto> adminViewAll() {
        return orderService.findAll();
    }
}

Custom security expression bean:

@Component("orderSecurity")
@RequiredArgsConstructor
public class OrderSecurityEvaluator {

    private final OrderRepository orderRepository;

    public boolean isOwner(Long orderId, Authentication authentication) {
        return orderRepository.findById(orderId)
            .map(order -> order.getUsername().equals(authentication.getName()))
            .orElse(false);
    }
}

Role Hierarchy

@Bean
public RoleHierarchy roleHierarchy() {
    return RoleHierarchyImpl.fromHierarchy("""
        ROLE_ADMIN > ROLE_MANAGER
        ROLE_MANAGER > ROLE_USER
        ROLE_USER > ROLE_GUEST
    """);
}

With this hierarchy, an ADMIN user implicitly has all permissions of MANAGER, USER, and GUEST without explicitly assigning all roles.

CORS Configuration

What it does: Controls which domains can make JavaScript requests to your API from a browser.

Why it exists: The Same-Origin Policy blocks cross-origin requests by default. Without CORS, your React app on localhost:3000 can't call your Spring API on localhost:8080.

How it works: Browser sends a preflight OPTIONS request with Origin header. Server responds with Access-Control-Allow-Origin. If the origin is allowed, the browser proceeds with the actual request. If not, the browser blocks the response (the server still processes the request!).

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration config = new CorsConfiguration();
    config.setAllowedOrigins(List.of(
        "https://shop.myapp.com",
        "https://admin.myapp.com"
    ));
    config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
    config.setAllowedHeaders(List.of("Authorization", "Content-Type", "X-Request-ID"));
    config.setExposedHeaders(List.of("X-Total-Count", "X-Page-Number"));
    config.setAllowCredentials(true);
    config.setMaxAge(3600L);  // cache preflight for 1 hour

    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/api/**", config);
    return source;
}

CSRF Protection

What it does: Prevents attackers from tricking a user's browser into making unwanted requests to your server using the user's existing session cookie.

Why it exists: If your app uses cookies for authentication (session-based), any website can include an <img> or <form> pointing to your server. The browser automatically attaches cookies. Without CSRF tokens, the server can't distinguish legitimate requests from forged ones.

When to disable:

• Stateless APIs using JWT in Authorization header (no cookies = no CSRF risk)
• Service-to-service communication
• APIs that NEVER use cookies for auth

When to keep enabled:

• Any app using session cookies (form login, remember-me)
• Server-rendered pages with forms

// Stateless API — disable safely
.csrf(csrf -> csrf.disable())

// SPA with cookie-based sessions — use cookie token repository
.csrf(csrf -> csrf
    .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
    .csrfTokenRequestHandler(new SpaCsrfTokenRequestHandler())
)

Session Management

.sessionManagement(session -> session
    // No session for JWT APIs
    .sessionCreationPolicy(SessionCreationPolicy.STATELESS)

    // OR: limit concurrent sessions (form login)
    .maximumSessions(1)
    .maxSessionsPreventsLogin(true)  // reject new login (vs expiring old session)
    .expiredUrl("/login?expired")
)

// Session fixation protection (on by default)
.sessionManagement(session -> session
    .sessionFixation().changeSessionId()  // default — migrates session on login
)

Security Headers

Spring Security sets protective headers by default:

.headers(headers -> headers
    .contentSecurityPolicy(csp -> csp
        .policyDirectives("default-src 'self'; script-src 'self' https://cdn.example.com"))
    .frameOptions(frame -> frame.sameOrigin())  // allow iframes from same origin
    .httpStrictTransportSecurity(hsts -> hsts
        .includeSubDomains(true)
        .maxAgeInSeconds(31536000))
)

JWT vs Session — The Tradeoff Table

This is a guaranteed interview question. Know the tradeoffs cold.

Securing Microservices

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart LR
    GW["🌐 API Gateway<br/>(validates JWT)"]
    GW --> SVC1["📦 Order Service"]
    GW --> SVC2["📦 Inventory Service"]
    GW --> SVC3["📦 Payment Service"]
    SVC1 -->|"service-to-service<br/>client-credentials"| SVC2
    IDP["🔐 Identity Provider<br/>(Keycloak/Auth0)"] -.->|"issues tokens"| GW
    IDP -.->|"JWKS endpoint"| SVC1
    IDP -.->|"JWKS endpoint"| SVC2

    style GW fill:#FEF3C7,stroke:#FCD34D,color:#1E40AF
    style IDP fill:#ECFDF5,stroke:#6EE7B7,color:#1E40AF

Pattern: Gateway validates, services trust

1. API Gateway validates the JWT (signature, expiration, issuer)
2. Gateway forwards request with validated claims in headers
3. Downstream services trust the gateway (internal network)
4. Service-to-service calls use Client Credentials grant (no user involved)

Pattern: Each service validates independently

1. Each service has the IdP's public key (from JWKS endpoint)
2. Each service validates the JWT independently
3. More secure (zero-trust) but slightly more latency

Common Interview Questions — Deep Answers

What Breaks — The Debugging Guide

403 vs 401 Confusion

Symptom: You get 403 Forbidden when you expect 401 Unauthorized (or vice versa).

Root cause: Spring Security returns 403 by default when authorization fails, even for unauthenticated users, because AnonymousAuthenticationFilter creates a dummy anonymous authentication. So the user IS "authenticated" (as anonymous) but lacks permission = 403.

Fix: Configure ExceptionHandling to return 401 for AuthenticationException:

.exceptionHandling(ex -> ex
    .authenticationEntryPoint(new HttpStatusEntryPoint(HttpStatus.UNAUTHORIZED))
)

Filter Order Bugs

Symptom: JWT filter doesn't seem to run, or runs but authentication isn't recognized.

Root cause: You registered the filter at the wrong position. If your JWT filter runs AFTER AuthorizationFilter, authorization is already denied before your filter authenticates.

Fix: Always use addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class) — this places your filter in the authentication phase, before authorization happens.

CORS + Security Conflict

Symptom: Preflight requests get 401. Everything works from Postman but not from the browser.

Root cause: Security filters run before CORS is handled. The OPTIONS preflight carries no auth credentials.

Fix: Add .cors(cors -> cors.configurationSource(yourSource)) to the SecurityFilterChain. This ensures CorsFilter is registered before auth filters.

@PreAuthorize Not Working

Symptom: @PreAuthorize annotations are completely ignored. Endpoints are open to everyone.

Root causes (in order of likelihood):

1. Missing @EnableMethodSecurity on a @Configuration class
2. Method is private (AOP proxy can't intercept)
3. Self-invocation: calling the annotated method from another method in the same class
4. Using @PreAuthorize on a class not managed by Spring (not a bean)

hasRole() Silent 403

Symptom: User has the correct role but gets 403. No error in logs.

Root cause: Authority stored as "ADMIN" but you're using hasRole("ADMIN") which looks for "ROLE_ADMIN".

Fix: Either store "ROLE_ADMIN" in your database, OR use hasAuthority("ADMIN") in your config. Pick one convention project-wide.

Production Checklist

Before deploying Spring Security to production, verify:

• HTTPS enforced (redirect HTTP to HTTPS or reject)
• CORS restricted to specific origins (not *)
• CSRF enabled for cookie-based auth, disabled for token-based
• Passwords hashed with BCrypt (cost >= 10) or Argon2id
• JWT secrets in a secrets manager (not application.yml)
• Access tokens are short-lived (15-30 min)
• Refresh token rotation implemented (detect token reuse)
• Rate limiting on /auth/login (prevent brute force)
• Account lockout after N failed attempts
• Security headers configured (CSP, HSTS, X-Frame-Options)
• @EnableMethodSecurity is present (verify with a test!)
• No permitAll() on sensitive endpoints by accident
• Custom AuthenticationEntryPoint returns proper 401 JSON (not HTML)
• Actuator endpoints secured (especially /actuator/env, /actuator/heapdump)
• Dependencies scanned for CVEs (OWASP dependency-check or Snyk)

Quick Reference — Annotations Cheat Sheet

// ═══════════════════════════════════════════
// METHOD-LEVEL SECURITY
// ═══════════════════════════════════════════

@PreAuthorize("hasRole('ADMIN')")                         // role check
@PreAuthorize("hasAuthority('ORDER_DELETE')")              // permission check
@PreAuthorize("#userId == authentication.principal.id")    // parameter binding
@PreAuthorize("@myBean.hasAccess(#id, authentication)")   // bean method call
@PreAuthorize("hasRole('ADMIN') and #amount < 10000")     // compound expression

@PostAuthorize("returnObject.owner == authentication.name")  // check return value
@PostFilter("filterObject.owner == authentication.name")     // filter collection

@Secured({"ROLE_ADMIN", "ROLE_MANAGER"})  // simple OR role check (no SpEL)
@RolesAllowed({"ADMIN", "MANAGER"})       // JSR-250 standard

// ═══════════════════════════════════════════
// INJECTING CURRENT USER
// ═══════════════════════════════════════════

@AuthenticationPrincipal UserDetails user       // inject principal in controller
@CurrentSecurityContext SecurityContext ctx      // inject full security context

// ═══════════════════════════════════════════
// CONFIGURATION
// ═══════════════════════════════════════════

@EnableWebSecurity          // enables Spring Security filter chain
@EnableMethodSecurity       // enables @PreAuthorize, @PostAuthorize
@EnableMethodSecurity(securedEnabled = true)    // also enables @Secured
@EnableMethodSecurity(jsr250Enabled = true)     // also enables @RolesAllowed

See Also

• JWT — Token structure, signing algorithms, and validation deep-dive
• OAuth 2.0 — Authorization flows, grant types, and PKCE
• Filters, Interceptors & AOP — Request processing pipeline layers