Security Engineering
with Spring Boot

// From any bean — no injection needed
SecurityContext ctx = SecurityContextHolder.getContext();
Authentication auth = ctx.getAuthentication();

String username = auth.getName();
Collection<? extends GrantedAuthority> roles = auth.getAuthorities();
Object principal = auth.getPrincipal(); // UserDetails object

// Typical pattern in a service
public void updateProfile(ProfileDTO dto) {
    String currentUser = SecurityContextHolder.getContext()
        .getAuthentication().getName();
    // use currentUser for audit logging, ownership checks, etc.
}

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    // Chain 1: API routes — stateless JWT
    @Bean
    @Order(1)
    public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
        return http
            .securityMatcher("/api/**")
            .sessionManagement(s -> s.sessionCreationPolicy(STATELESS))
            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .build();
    }

    // Chain 2: Actuator — separate access rules
    @Bean
    @Order(2)
    public SecurityFilterChain actuatorChain(HttpSecurity http) throws Exception {
        return http
            .securityMatcher("/actuator/**")
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/health").permitAll()
                .anyRequest().hasRole("ADMIN"))
            .httpBasic(Customizer.withDefaults())
            .build();
    }
}

@Service
@RequiredArgsConstructor
public class AppUserDetailsService implements UserDetailsService {

    private final UserRepository userRepo;

    @Override
    public UserDetails loadUserByUsername(String email)
            throws UsernameNotFoundException {
        User user = userRepo.findByEmail(email)
            .orElseThrow(() -> new UsernameNotFoundException(
                "User not found: " + email));

        return org.springframework.security.core.userdetails.User
            .withUsername(user.getEmail())
            .password(user.getPasswordHash())   // already hashed
            .roles(user.getRole().name())        // "ADMIN" → "ROLE_ADMIN"
            .accountLocked(user.isLocked())
            .accountExpired(false)
            .credentialsExpired(false)
            .build();
    }
}

// Wire it in SecurityConfig
@Bean
public AuthenticationManager authManager(
        UserDetailsService uds, PasswordEncoder encoder) {
    DaoAuthenticationProvider provider = new DaoAuthenticationProvider();
    provider.setUserDetailsService(uds);
    provider.setPasswordEncoder(encoder);
    return new ProviderManager(provider);
}

// Custom token type
public class ApiKeyAuthenticationToken extends AbstractAuthenticationToken {
    private final String apiKey;
    public ApiKeyAuthenticationToken(String apiKey) {
        super(null); // no authorities yet
        this.apiKey = apiKey;
        setAuthenticated(false);
    }
    @Override public Object getCredentials() { return apiKey; }
    @Override public Object getPrincipal() { return apiKey; }
}

// Provider that validates API keys
@Component
public class ApiKeyAuthenticationProvider implements AuthenticationProvider {

    private final ApiKeyRepository apiKeyRepo;

    @Override
    public Authentication authenticate(Authentication auth)
            throws AuthenticationException {
        String key = (String) auth.getCredentials();
        ApiKey stored = apiKeyRepo.findByKeyHash(sha256(key))
            .orElseThrow(() -> new BadCredentialsException("Invalid API key"));

        if (stored.isExpired()) throw new CredentialsExpiredException("API key expired");

        List<GrantedAuthority> authorities =
            List.of(new SimpleGrantedAuthority("ROLE_" + stored.getRole()));

        ApiKeyAuthenticationToken authenticated =
            new ApiKeyAuthenticationToken(key);
        authenticated.setAuthenticated(true);
        // set authorities on the authenticated token
        return new UsernamePasswordAuthenticationToken(
            stored.getOwner(), null, authorities);
    }

    @Override
    public boolean supports(Class<?> authentication) {
        return ApiKeyAuthenticationToken.class.isAssignableFrom(authentication);
    }
}

http.authorizeHttpRequests(auth -> auth
    // Public endpoints — no auth needed
    .requestMatchers("/api/auth/**").permitAll()
    .requestMatchers(HttpMethod.GET, "/api/products/**").permitAll()
    .requestMatchers("/actuator/health", "/actuator/info").permitAll()

    // Role-based access
    .requestMatchers("/api/admin/**").hasRole("ADMIN")
    .requestMatchers("/api/manager/**").hasAnyRole("ADMIN", "MANAGER")

    // Authority-based (more granular than roles)
    .requestMatchers(HttpMethod.DELETE, "/api/**").hasAuthority("product:delete")
    .requestMatchers(HttpMethod.POST, "/api/products").hasAuthority("product:write")

    // Everything else requires authentication
    .anyRequest().authenticated()
);

// Enable in config
@Configuration
@EnableMethodSecurity   // replaces deprecated @EnableGlobalMethodSecurity
public class MethodSecurityConfig { }

// Service layer authorization
@Service
public class OrderService {

    // Simple role check
    @PreAuthorize("hasRole('ADMIN')")
    public List<Order> getAllOrders() { ... }

    // Authority check
    @PreAuthorize("hasAuthority('order:write')")
    public Order createOrder(CreateOrderRequest req) { ... }

    // Check ownership — user can only access their own orders
    @PreAuthorize("#orderId != null and @orderSecurity.isOwner(#orderId, authentication)")
    public Order getOrder(Long orderId) { ... }

    // Can access if admin OR owner
    @PreAuthorize("hasRole('ADMIN') or #userId == authentication.name")
    public UserProfile getProfile(String userId) { ... }

    // Filter returned collection — only return orders user owns
    @PostFilter("filterObject.userId == authentication.name")
    public List<Order> getMyOrders() { ... }

    // Filter input collection before passing to method
    @PreFilter("filterObject.userId == authentication.name")
    public void processOrders(List<Order> orders) { ... }
}

// Custom security bean (referenced as @orderSecurity above)
@Component("orderSecurity")
public class OrderSecurityService {
    public boolean isOwner(Long orderId, Authentication auth) {
        Order order = orderRepo.findById(orderId).orElseThrow();
        return order.getUserId().equals(auth.getName());
    }
}

// Register the encoder as a bean
@Bean
public PasswordEncoder passwordEncoder() {
    // strength/cost factor: 10-12 is standard for production
    // higher = slower = better, but watch CPU on registration endpoints
    return new BCryptPasswordEncoder(12);
}

// Usage in registration
@Service
public class AuthService {
    private final PasswordEncoder encoder;
    private final UserRepository userRepo;

    public User register(RegisterRequest req) {
        String hashed = encoder.encode(req.getPassword());
        // hashed looks like: $2a$12$... (60 chars, includes salt)
        return userRepo.save(new User(req.getEmail(), hashed));
    }

    // Spring calls encoder.matches() automatically during login
    // You never need to call it manually in the login flow
}

@Bean
public PasswordEncoder passwordEncoder() {
    // Stores hashes as: {bcrypt}$2a$12$..., {argon2}..., {noop}plaintext
    Map<String, PasswordEncoder> encoders = new HashMap<>();
    encoders.put("bcrypt", new BCryptPasswordEncoder(12));
    encoders.put("argon2", new Argon2PasswordEncoder(16, 32, 1, 65536, 10));
    encoders.put("noop", NoOpPasswordEncoder.getInstance()); // legacy ONLY

    // New passwords use bcrypt
    DelegatingPasswordEncoder delegate = new DelegatingPasswordEncoder("bcrypt", encoders);
    return delegate;
}

// Migration strategy:
// 1. Change encoder bean to DelegatingPasswordEncoder
// 2. On next login: matches() succeeds with old algorithm
// 3. After successful login, re-encode with new algorithm and save
// Users migrate transparently without password resets

@PostMapping("/api/auth/refresh")
public ResponseEntity<TokenResponse> refreshToken(
        @RequestBody RefreshTokenRequest req) {

    String refreshToken = req.getRefreshToken();

    // 1. Validate JWT structure and expiry
    String username = jwtService.extractUsername(refreshToken);

    // 2. Check the token exists in DB (enables server-side revocation)
    RefreshToken storedToken = refreshTokenRepo
        .findByToken(hashToken(refreshToken))
        .orElseThrow(() -> new InvalidTokenException("Refresh token not found"));

    if (storedToken.isRevoked() || storedToken.isExpired()) {
        // Possible token reuse attack — revoke entire family
        refreshTokenRepo.revokeAllByUserId(storedToken.getUserId());
        throw new SecurityException("Token reuse detected");
    }

    // 3. Rotate: revoke old refresh token, issue new pair
    storedToken.setRevoked(true);
    refreshTokenRepo.save(storedToken);

    UserDetails user = userDetailsService.loadUserByUsername(username);
    String newAccess = jwtService.generateAccessToken(user);
    String newRefresh = jwtService.generateRefreshToken(user);

    // 4. Store new refresh token hash
    refreshTokenRepo.save(new RefreshToken(storedToken.getUserId(),
        hashToken(newRefresh)));

    return ResponseEntity.ok(new TokenResponse(newAccess, newRefresh));
}

// For REST APIs using stateless JWT — CSRF protection is not needed
// Reason: CSRF exploits cookies. JWT in Authorization header is same-origin only.
http.csrf(AbstractHttpConfigurer::disable);

// For session-based web apps (server-rendered, or SPA using cookies):
http.csrf(csrf -> csrf
    .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
    // Required for Spring Security 6.x — explicitly handle token subscription
    .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler())
);

// The frontend must then read the XSRF-TOKEN cookie and send it
// as X-XSRF-TOKEN header on all mutating requests (POST/PUT/DELETE)

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration config = new CorsConfiguration();

    // Explicit allowed origins — never use "*" with credentials
    config.setAllowedOrigins(List.of(
        "https://app.yourdomain.com",
        "https://admin.yourdomain.com"
    ));

    // OR: pattern matching for subdomains
    config.setAllowedOriginPatterns(List.of("https://*.yourdomain.com"));

    config.setAllowedMethods(List.of("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"));
    config.setAllowedHeaders(List.of("Authorization", "Content-Type", "X-Request-ID"));
    config.setExposedHeaders(List.of("X-Total-Count", "X-Request-ID")); // frontend can read
    config.setAllowCredentials(true);  // required for cookies/Authorization header
    config.setMaxAge(3600L);           // preflight cache duration in seconds

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

http.sessionManagement(session -> session
    // CHANGE_SESSION_ID: creates new session on login — default, recommended
    .sessionFixation(SessionManagementConfigurer.SessionFixationConfigurer::changeSessionId)

    // For stateless JWT APIs:
    .sessionCreationPolicy(SessionCreationPolicy.STATELESS)

    // Limit concurrent sessions — prevents session sharing/theft
    .maximumSessions(1)
    .maxSessionsPreventsLogin(false) // false = new login invalidates old session
);

<!-- pom.xml -->
<dependency>
  <groupId>com.bucket4j</groupId>
  <artifactId>bucket4j-core</artifactId>
  <version>8.7.0</version>
</dependency>

// Rate limit filter — 20 requests per minute per IP
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class RateLimitFilter extends OncePerRequestFilter {

    // ConcurrentHashMap for in-memory; swap for Redis/Hazelcast in distributed setup
    private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();

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

        String key = getKey(req);
        Bucket bucket = buckets.computeIfAbsent(key, k -> createBucket());

        ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);

        if (probe.isConsumed()) {
            res.setHeader("X-Rate-Limit-Remaining",
                String.valueOf(probe.getRemainingTokens()));
            chain.doFilter(req, res);
        } else {
            res.setStatus(429);
            res.setHeader("X-Rate-Limit-Retry-After-Seconds",
                String.valueOf(probe.getNanosToWaitForRefill() / 1_000_000_000));
            res.getWriter().write("{\"error\": \"Rate limit exceeded\"}");
        }
    }

    private Bucket createBucket() {
        return Bucket.builder()
            .addLimit(Bandwidth.builder()
                .capacity(20)
                .refillGreedy(20, Duration.ofMinutes(1))
                .build())
            .build();
    }

    private String getKey(HttpServletRequest req) {
        // Use authenticated username if available, otherwise IP
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (auth != null && auth.isAuthenticated() &&
                !(auth instanceof AnonymousAuthenticationToken)) {
            return "user:" + auth.getName();
        }
        return "ip:" + req.getRemoteAddr();
    }
}

@PostMapping("/api/auth/login")
public ResponseEntity<TokenResponse> login(@Valid @RequestBody LoginRequest req,
                                             HttpServletRequest httpReq) {
    String ip = getClientIp(httpReq);
    String key = "login:" + ip;

    // 1. Check failed attempt count in Redis
    Integer attempts = (Integer) redisTemplate.opsForValue().get(key);
    if (attempts != null && attempts >= 5) {
        throw new TooManyAttemptsException("Account temporarily locked. Try in 15 minutes.");
    }

    try {
        // 2. Attempt authentication
        Authentication auth = authManager.authenticate(
            new UsernamePasswordAuthenticationToken(req.getEmail(), req.getPassword()));

        // 3. Success — clear failure count
        redisTemplate.delete(key);

        UserDetails user = (UserDetails) auth.getPrincipal();
        String access = jwtService.generateAccessToken(user);
        String refresh = jwtService.generateRefreshToken(user);

        // 4. Store refresh token hash
        saveRefreshToken(user.getUsername(), refresh);

        return ResponseEntity.ok(new TokenResponse(access, refresh));

    } catch (BadCredentialsException e) {
        // 5. Increment failure count with TTL
        redisTemplate.opsForValue().increment(key);
        redisTemplate.expire(key, Duration.ofMinutes(15));
        // Return generic message — don't leak whether email exists
        throw new BadCredentialsException("Invalid credentials");
    }
}

http.headers(headers -> headers
    // Prevent clickjacking — disallow embedding in iframes
    .frameOptions(frame -> frame.deny())

    // Force HTTPS for 1 year — includes subdomains
    .httpStrictTransportSecurity(hsts -> hsts
        .includeSubDomains(true)
        .maxAgeInSeconds(31536000))

    // Prevent MIME type sniffing
    .contentTypeOptions(Customizer.withDefaults())

    // Referrer policy — don't leak full URL to external sites
    .referrerPolicy(ref -> ref.policy(ReferrerPolicyHeaderWriter.ReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN))

    // Content Security Policy — restrict script sources
    .contentSecurityPolicy(csp -> csp
        .policyDirectives("default-src 'self'; " +
                          "script-src 'self' 'nonce-{NONCE}'; " +
                          "style-src 'self' https://fonts.googleapis.com; " +
                          "img-src 'self' data:; " +
                          "frame-ancestors 'none'"))
);

// Extend default expressions with custom methods
public class CustomMethodSecurityExpressionRoot
        extends SecurityExpressionRoot
        implements MethodSecurityExpressionOperations {

    private final TenantService tenantService;
    private Object filterObject;
    private Object returnObject;

    public CustomMethodSecurityExpressionRoot(Authentication auth,
                                               TenantService tenantService) {
        super(auth);
        this.tenantService = tenantService;
    }

    // Custom expression: @PreAuthorize("belongsToTenant(#tenantId)")
    public boolean belongsToTenant(Long tenantId) {
        String currentUser = getAuthentication().getName();
        return tenantService.userBelongsToTenant(currentUser, tenantId);
    }

    // Custom expression: @PreAuthorize("hasPlan('ENTERPRISE')")
    public boolean hasPlan(String planName) {
        return getAuthentication().getAuthorities().stream()
            .anyMatch(a -> a.getAuthority().equals("PLAN_" + planName));
    }

    @Override public Object getFilterObject() { return filterObject; }
    @Override public void setFilterObject(Object o) { filterObject = o; }
    @Override public Object getReturnObject() { return returnObject; }
    @Override public void setReturnObject(Object o) { returnObject = o; }
    @Override public Object getThis() { return this; }
}

// Register the custom expression handler
@Bean
public MethodSecurityExpressionHandler methodSecurityExpressionHandler() {
    DefaultMethodSecurityExpressionHandler handler =
        new DefaultMethodSecurityExpressionHandler() {
            @Override
            protected MethodSecurityExpressionOperations createSecurityExpressionRoot(
                    Authentication auth, MethodInvocation mi) {
                return new CustomMethodSecurityExpressionRoot(auth, tenantService);
            }
        };
    return handler;
}

@Service
public class ProjectService {

    // Only project members can view
    @PreAuthorize("@projectSecurity.isMember(#projectId, authentication) " +
                  "or hasRole('ADMIN')")
    public Project getProject(Long projectId) { ... }

    // Only project OWNER or admin can delete
    @PreAuthorize("@projectSecurity.isOwner(#projectId, authentication) " +
                  "or hasRole('ADMIN')")
    @Transactional
    public void deleteProject(Long projectId) { ... }

    // Return only projects the user can see (post-filter)
    @PostFilter("@projectSecurity.isMember(filterObject.id, authentication) " +
                "or hasRole('ADMIN')")
    public List<Project> getAllProjects() {
        return projectRepo.findAll(); // Spring filters the result
    }
}

@Component("projectSecurity")
@RequiredArgsConstructor
public class ProjectSecurityService {
    private final ProjectMemberRepository memberRepo;

    public boolean isMember(Long projectId, Authentication auth) {
        return memberRepo.existsByProjectIdAndUserEmail(projectId, auth.getName());
    }

    public boolean isOwner(Long projectId, Authentication auth) {
        return memberRepo.existsByProjectIdAndUserEmailAndRole(
            projectId, auth.getName(), "OWNER");
    }
}