Java Spring Boot 3.4 & React 19: Enterprise Security Architecture – Stateless JWT, Method-Level RBAC & OWASP Top 10 Defense

// backend/src/main/java/com/elearning/security/JwtProvider.java
@Component
public class JwtProvider {

    private final SecretKey secretKey;
    private final long accessTokenExpirationMs;
    private final long refreshTokenExpirationMs;

    public JwtProvider(
            @Value("${app.jwt.secret}") String secret,
            @Value("${app.jwt.access-token-expiration-ms:900000}") long accessTokenExpirationMs,
            @Value("${app.jwt.refresh-token-expiration-ms:604800000}") long refreshTokenExpirationMs
    ) {
        if (secret == null || secret.trim().isEmpty()) {
            throw new IllegalStateException("CRITICAL: app.jwt.secret is not configured! Please provide JWT_SECRET environment variable.");
        }
        byte[] keyBytes = Decoders.BASE64.decode(secret.trim());
        
        // Cryptographic Enforcement: Must be at least 256 bits (32 bytes) for HMAC-SHA256
        if (keyBytes.length < 32) {
            throw new IllegalArgumentException("CRITICAL: JWT secret key must be at least 256 bits (32 bytes) long for HMAC-SHA256!");
        }
        this.secretKey = Keys.hmacShaKeyFor(keyBytes);
        this.accessTokenExpirationMs = accessTokenExpirationMs; // 15 minutes default
        this.refreshTokenExpirationMs = refreshTokenExpirationMs; // 7 days default
    }

    public String generateAccessToken(UserPrincipal userPrincipal) {
        Date now = new Date();
        Date expiryDate = new Date(now.getTime() + accessTokenExpirationMs);

        List<String> roles = userPrincipal.getAuthorities().stream()
                .map(GrantedAuthority::getAuthority)
                .collect(Collectors.toList());

        var builder = Jwts.builder()
                .subject(userPrincipal.getId().toString())
                .claim("email", userPrincipal.getEmail())
                .claim("name", userPrincipal.getName())
                .claim("roles", roles)
                .issuedAt(now)
                .expiration(expiryDate)
                .signWith(secretKey);

        // Append administrative impersonator audit claim if active
        if (userPrincipal.getImpersonatorAdminId() != null) {
            builder.claim("impersonatorAdminId", userPrincipal.getImpersonatorAdminId());
        }

        return builder.compact();
    }
}

// backend/src/main/java/com/elearning/security/JwtAuthenticationFilter.java
@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtProvider jwtProvider;
    private final CustomUserDetailsService userDetailsService;

    @Override
    protected void doFilterInternal(
            @NonNull HttpServletRequest request,
            @NonNull HttpServletResponse response,
            @NonNull FilterChain filterChain
    ) throws ServletException, IOException {
        String token = getJwtFromRequest(request);

        if (StringUtils.hasText(token) && jwtProvider.validateToken(token)) {
            Long userId = jwtProvider.getUserIdFromToken(token);
            Long impersonatorAdminId = jwtProvider.getImpersonatorAdminIdFromToken(token);

            // Load immutable user principal including current authority grants
            UserDetails userDetails = userDetailsService.loadUserById(userId, impersonatorAdminId);
            
            UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
                    userDetails,
                    null,
                    userDetails.getAuthorities()
            );
            authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));

            // Establish security context for downstream thread execution
            SecurityContextHolder.getContext().setAuthentication(authentication);
        }

        filterChain.doFilter(request, response);
    }

    private String getJwtFromRequest(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");
        if (StringUtils.hasText(bearerToken) && bearerToken.startsWith("Bearer ")) {
            return bearerToken.substring(7);
        }
        return null;
    }
}

// Coarse-grained URL matching (Necessary, but NOT sufficient on its own)
http.authorizeHttpRequests(auth -> auth
    .requestMatchers("/api/v1/admin/**").hasRole("ADMIN")
    .requestMatchers("/api/v1/teacher/**").hasAnyRole("ADMIN", "TEACHER")
    .requestMatchers("/api/v1/student/**").hasAnyRole("ADMIN", "STUDENT")
    .anyRequest().authenticated()
);

// backend/src/main/java/com/elearning/config/SecurityConfig.java
@Configuration
@EnableWebSecurity
@EnableMethodSecurity(prePostEnabled = true) // Activates @PreAuthorize and @PostAuthorize
@RequiredArgsConstructor
public class SecurityConfig {
    // ...
}

// backend/src/main/java/com/elearning/security/UserPrincipal.java
public static UserPrincipal create(User user, Long impersonatorAdminId) {
    Collection<GrantedAuthority> authorities = user.getRoles().stream()
            .map(role -> new SimpleGrantedAuthority(role.getName().name())) // e.g. "ROLE_ADMIN", "ROLE_TEACHER"
            .collect(Collectors.toList());

    return new UserPrincipal(
            user.getId(),
            user.getName(),
            user.getEmail(),
            user.getPassword(),
            user.isActive(),
            authorities,
            impersonatorAdminId
    );
}

// backend/src/main/java/com/elearning/modules/exam/controller/ExamController.java
@RestController
@RequestMapping("/api/v1/exams")
@RequiredArgsConstructor
public class ExamController {

    private final ExamService examService;

    // Both Students and Teachers can list accessible exams, but service filters by enrollment
    @GetMapping
    public ResponseEntity<ApiResponse<List<ExamResponse>>> getExams(
            @AuthenticationPrincipal UserPrincipal principal) {
        return ResponseEntity.ok(ApiResponse.success(examService.getExamsForUser(principal), "Exams fetched"));
    }

    // Only Teachers and Admins can create new examinations
    @PostMapping
    @PreAuthorize("hasAnyRole('ADMIN', 'TEACHER')")
    public ResponseEntity<ApiResponse<ExamResponse>> createExam(
            @Valid @RequestBody ExamDto dto,
            @AuthenticationPrincipal UserPrincipal principal) {
        ExamResponse response = examService.createExam(dto, principal);
        return ResponseEntity.status(HttpStatus.CREATED).body(ApiResponse.success(response, "Exam created"));
    }

    // Updating exam metadata is restricted to Teachers and Admins
    @PutMapping("/{id}")
    @PreAuthorize("hasAnyRole('ADMIN', 'TEACHER')")
    public ResponseEntity<ApiResponse<ExamResponse>> updateExam(
            @PathVariable Long id,
            @Valid @RequestBody ExamDto dto,
            @AuthenticationPrincipal UserPrincipal principal) {
        return ResponseEntity.ok(ApiResponse.success(examService.updateExam(id, dto, principal), "Exam updated"));
    }

    // Question bank manipulation restricted to faculty
    @PostMapping("/{id}/questions")
    @PreAuthorize("hasAnyRole('ADMIN', 'TEACHER')")
    public ResponseEntity<ApiResponse<QuestionResponse>> addQuestion(
            @PathVariable Long id,
            @Valid @RequestBody QuestionDto dto,
            @AuthenticationPrincipal UserPrincipal principal) {
        return ResponseEntity.status(HttpStatus.CREATED).body(
                ApiResponse.success(examService.addQuestion(id, dto, principal), "Question added")
        );
    }
}

// backend/src/main/java/com/elearning/modules/exam/service/ExamService.java
@Transactional
public void deleteExam(Long id, UserPrincipal principal) {
    Examination exam = examRepository.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("Examination not found with id: " + id));

    // Admin can delete any exam; Teachers can only delete their own exams
    boolean isAdmin = principal.getAuthorities().stream()
            .anyMatch(a -> a.getAuthority().equals("ROLE_ADMIN"));
    boolean isOwner = exam.getTeacher().getId().equals(principal.getId());

    if (!isAdmin && !isOwner) {
        throw new SecurityException("Forbidden: You do not have permission to delete an examination created by another teacher.");
    }

    examRepository.delete(exam);
}

// backend/src/main/java/com/elearning/security/RateLimitingFilter.java
@Component
@Slf4j
public class RateLimitingFilter extends OncePerRequestFilter {

    private final Map<String, Bucket> authIpBuckets = new ConcurrentHashMap<>();
    private final Map<String, Bucket> submitIpBuckets = new ConcurrentHashMap<>();
    private final Map<String, Bucket> generalIpBuckets = new ConcurrentHashMap<>();

    // Multi-Tier Rate Limit Capacities
    private static final int AUTH_CAPACITY = 10;       // 10 login/auth requests per minute per IP
    private static final int SUBMIT_CAPACITY = 60;     // 60 autosave/submit requests per minute per IP
    private static final int GENERAL_CAPACITY = 120;   // 120 general API requests per minute per IP

    private Bucket createBucket(int capacity, Duration duration) {
        Bandwidth limit = Bandwidth.classic(capacity, Refill.greedy(capacity, duration));
        return Bucket.builder().addLimit(limit).build();
    }

    @Override
    protected boolean shouldNotFilter(@NonNull HttpServletRequest request) {
        String path = request.getRequestURI();
        // Skip rate limiting for static documentation, health probes, and preflight CORS
        return "OPTIONS".equalsIgnoreCase(request.getMethod())
                || path.startsWith("/actuator")
                || path.startsWith("/swagger-ui")
                || path.startsWith("/v3/api-docs")
                || path.startsWith("/ws");
    }

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

        String clientIp = LoginRateLimiterService.getClientIp(request);
        String requestUri = request.getRequestURI();

        // Tier 1: Strictest limit on Auth endpoints (Login / Register)
        if (requestUri.startsWith("/api/v1/auth/login") || requestUri.startsWith("/api/v1/auth/register")) {
            Bucket authBucket = authIpBuckets.computeIfAbsent(
                    clientIp, k -> createBucket(AUTH_CAPACITY, Duration.ofMinutes(1))
            );
            if (!authBucket.tryConsume(1)) {
                log.warn("Rate limit [AUTH] exceeded for IP {} on {}", clientIp, requestUri);
                sendRateLimitResponse(response, "Too many authentication attempts. Please wait 1 minute before retrying.");
                return;
            }
        }

        // Tier 2: Anti-flood protection for exam autosave and submissions
        else if (requestUri.contains("/exams/") && (requestUri.endsWith("/submit") || requestUri.endsWith("/answer"))) {
            Bucket submitBucket = submitIpBuckets.computeIfAbsent(
                    clientIp, k -> createBucket(SUBMIT_CAPACITY, Duration.ofMinutes(1))
            );
            if (!submitBucket.tryConsume(1)) {
                log.warn("Rate limit [EXAM SUBMIT] exceeded for IP {} on {}", clientIp, requestUri);
                sendRateLimitResponse(response, "High exam submission velocity detected. Please wait a moment.");
                return;
            }
        }

        // Tier 3: General API tier for all other endpoints
        else if (requestUri.startsWith("/api/v1")) {
            Bucket generalBucket = generalIpBuckets.computeIfAbsent(
                    clientIp, k -> createBucket(GENERAL_CAPACITY, Duration.ofMinutes(1))
            );
            if (!generalBucket.tryConsume(1)) {
                log.warn("Rate limit [GENERAL API] exceeded for IP {} on {}", clientIp, requestUri);
                sendRateLimitResponse(response, "API request rate limit exceeded. Please throttle your requests.");
                return;
            }
        }

        filterChain.doFilter(request, response);
    }

    private void sendRateLimitResponse(HttpServletResponse response, String message) throws IOException {
        response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value()); // HTTP 429
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setCharacterEncoding("UTF-8");
        response.setHeader("Retry-After", "60");
        response.setHeader("X-RateLimit-Retry-After-Seconds", "60");

        String jsonPayload = String.format("{\"success\":false,\"message\":\"%s\",\"data\":null}", message);
        response.getWriter().write(jsonPayload);
        response.getWriter().flush();
    }
}

// backend/src/main/java/com/elearning/config/SecurityConfig.java
http
    .addFilterBefore(rateLimitingFilter, LogoutFilter.class)
    .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);

@Bean
public FilterRegistrationBean<RateLimitingFilter> rateLimitingFilterRegistration(RateLimitingFilter filter) {
    FilterRegistrationBean<RateLimitingFilter> registration = new FilterRegistrationBean<>(filter);
    registration.setEnabled(false); // Prevents duplicate execution by Servlet container
    return registration;
}

// backend/src/main/java/com/elearning/modules/auth/controller/AuthController.java
@PostMapping("/admin/impersonate/{userId}")
@PreAuthorize("hasRole('ADMIN')")
@Operation(summary = "Start Impersonation", description = "Admin can impersonate a teacher or student user")
public ResponseEntity<ApiResponse<AuthResponse>> impersonate(
        @PathVariable Long userId,
        @AuthenticationPrincipal UserPrincipal adminPrincipal
) {
    AuthResponse response = authService.impersonate(userId, adminPrincipal);
    return ResponseEntity.ok(ApiResponse.ok(response, "Impersonation started successfully"));
}

@PostMapping("/admin/stop-impersonate")
@Operation(summary = "Stop Impersonation", description = "Revert impersonated session back to administrator")
public ResponseEntity<ApiResponse<AuthResponse>> stopImpersonate(
        @AuthenticationPrincipal UserPrincipal currentPrincipal
) {
    AuthResponse response = authService.stopImpersonate(currentPrincipal);
    return ResponseEntity.ok(ApiResponse.ok(response, "Returned to admin session"));
}