Spring Boot Security Best Practices: A Comprehensive Guide

Security is a critical aspect of any application, and Spring Boot provides robust tools to implement comprehensive security measures. This guide covers essential security practices for Spring Boot applications to protect against common vulnerabilities and threats.

Authentication and Authorization

JWT Authentication

JSON Web Tokens (JWT) provide a stateless authentication mechanism:

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    
    private final JwtAuthenticationFilter jwtAuthFilter;
    private final AuthenticationProvider authenticationProvider;
    
    public SecurityConfig(
            JwtAuthenticationFilter jwtAuthFilter,
            AuthenticationProvider authenticationProvider) {
        this.jwtAuthFilter = jwtAuthFilter;
        this.authenticationProvider = authenticationProvider;
    }
    
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .authorizeHttpRequests()
            .requestMatchers("/api/v1/auth/**").permitAll()
            .anyRequest().authenticated()
            .and()
            .sessionManagement()
            .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            .and()
            .authenticationProvider(authenticationProvider)
            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);
            
        return http.build();
    }
}

JWT Filter Implementation

@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {
    
    private final JwtService jwtService;
    private final UserDetailsService userDetailsService;
    
    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {
        
        final String authHeader = request.getHeader("Authorization");
        final String jwt;
        final String userEmail;
        
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            filterChain.doFilter(request, response);
            return;
        }
        
        jwt = authHeader.substring(7);
        userEmail = jwtService.extractUsername(jwt);
        
        if (userEmail != null && SecurityContextHolder.getContext().getAuthentication() == null) {
            UserDetails userDetails = this.userDetailsService.loadUserByUsername(userEmail);
            
            if (jwtService.isTokenValid(jwt, userDetails)) {
                UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(
                    userDetails,
                    null,
                    userDetails.getAuthorities()
                );
                authToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                SecurityContextHolder.getContext().setAuthentication(authToken);
            }
        }
        
        filterChain.doFilter(request, response);
    }
}

JWT Service

@Service
public class JwtService {
    
    @Value("${application.security.jwt.secret-key}")
    private String secretKey;
    
    @Value("${application.security.jwt.expiration}")
    private long jwtExpiration;
    
    @Value("${application.security.jwt.refresh-token.expiration}")
    private long refreshExpiration;
    
    public String extractUsername(String token) {
        return extractClaim(token, Claims::getSubject);
    }
    
    public <T> T extractClaim(String token, Function<Claims, T> claimsResolver) {
        final Claims claims = extractAllClaims(token);
        return claimsResolver.apply(claims);
    }
    
    public String generateToken(UserDetails userDetails) {
        return generateToken(new HashMap<>(), userDetails);
    }
    
    public String generateToken(
            Map<String, Object> extraClaims,
            UserDetails userDetails) {
        return buildToken(extraClaims, userDetails, jwtExpiration);
    }
    
    public String generateRefreshToken(UserDetails userDetails) {
        return buildToken(new HashMap<>(), userDetails, refreshExpiration);
    }
    
    private String buildToken(
            Map<String, Object> extraClaims,
            UserDetails userDetails,
            long expiration) {
        return Jwts
            .builder()
            .setClaims(extraClaims)
            .setSubject(userDetails.getUsername())
            .setIssuedAt(new Date(System.currentTimeMillis()))
            .setExpiration(new Date(System.currentTimeMillis() + expiration))
            .signWith(getSignInKey(), SignatureAlgorithm.HS256)
            .compact();
    }
    
    public boolean isTokenValid(String token, UserDetails userDetails) {
        final String username = extractUsername(token);
        return (username.equals(userDetails.getUsername())) && !isTokenExpired(token);
    }
    
    private boolean isTokenExpired(String token) {
        return extractExpiration(token).before(new Date());
    }
    
    private Date extractExpiration(String token) {
        return extractClaim(token, Claims::getExpiration);
    }
    
    private Claims extractAllClaims(String token) {
        return Jwts
            .parserBuilder()
            .setSigningKey(getSignInKey())
            .build()
            .parseClaimsJws(token)
            .getBody();
    }
    
    private Key getSignInKey() {
        byte[] keyBytes = Decoders.BASE64.decode(secretKey);
        return Keys.hmacShaKeyFor(keyBytes);
    }
}

Role-Based Access Control

Implement fine-grained access control with method-level security:

@Configuration
@EnableMethodSecurity
public class MethodSecurityConfig {
    // Configuration for method security
}

@Service
public class UserService {
    
    @PreAuthorize("hasRole('ADMIN')")
    public List<User> getAllUsers() {
        // Only accessible to users with ADMIN role
        return userRepository.findAll();
    }
    
    @PreAuthorize("hasRole('ADMIN') or #id == authentication.principal.id")
    public User getUserById(Long id) {
        // Accessible to ADMIN or the user themselves
        return userRepository.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("User not found"));
    }
    
    @PreAuthorize("hasAnyRole('ADMIN', 'MANAGER')")
    public void deleteUser(Long id) {
        // Only accessible to ADMIN or MANAGER roles
        userRepository.deleteById(id);
    }
}

CSRF Protection

Enable CSRF Protection

CSRF protection is enabled by default in Spring Security:

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // Enable CSRF protection
            .csrf(csrf -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
            )
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/public/**").permitAll()
                .anyRequest().authenticated()
            );
            
        return http.build();
    }
}

CSRF Protection for REST APIs

For REST APIs that use tokens, you might disable CSRF for specific endpoints:

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // Disable CSRF for API endpoints that use JWT
            .csrf(csrf -> csrf
                .ignoringRequestMatchers("/api/v1/auth/**")
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
            )
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/v1/auth/**").permitAll()
                .anyRequest().authenticated()
            );
            
        return http.build();
    }
}

Secure Headers

HTTP Security Headers

Configure security headers to protect against common attacks:

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // Configure security headers
            .headers(headers -> headers
                .contentSecurityPolicy(csp -> csp
                    .policyDirectives("default-src 'self'; script-src 'self' https://trusted.cdn.com")
                )
                .frameOptions(frame -> frame.deny())
                .xssProtection(xss -> xss.enable())
                .contentTypeOptions(contentType -> contentType.disable())
                .referrerPolicy(referrer -> referrer
                    .policy(ReferrerPolicyHeaderWriter.ReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN)
                )
                .permissionsPolicy(permissions -> permissions
                    .policy("camera=(), microphone=(), geolocation=()")
                )
            );
            
        return http.build();
    }
}

Password Security

Password Encoding

Use strong password hashing algorithms:

@Configuration
public class ApplicationConfig {
    
    @Bean
    public PasswordEncoder passwordEncoder() {
        // Use BCrypt for password hashing
        return new BCryptPasswordEncoder();
    }
    
    // Alternative: Use Argon2 (stronger but more resource-intensive)
    @Bean
    public PasswordEncoder argon2PasswordEncoder() {
        return new Argon2PasswordEncoder(
            16,  // saltLength
            32,  // hashLength
            1,   // parallelism
            4096, // memory
            3    // iterations
        );
    }
}

Password Validation

Implement strong password policies:

@Component
public class PasswordValidator {
    
    private static final String PASSWORD_PATTERN = 
        "^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z])(?=.*[@#$%^&+=])(?=\\S+$).{8,}$";
    
    private final Pattern pattern = Pattern.compile(PASSWORD_PATTERN);
    
    public boolean isValid(String password) {
        if (password == null) {
            return false;
        }
        
        Matcher matcher = pattern.matcher(password);
        return matcher.matches();
    }
    
    public List<String> getPasswordRequirements() {
        return List.of(
            "At least 8 characters long",
            "Contains at least one digit",
            "Contains at least one lowercase letter",
            "Contains at least one uppercase letter",
            "Contains at least one special character (@#$%^&+=)",
            "No whitespace allowed"
        );
    }
}

Input Validation and Sanitization

Request Validation

Validate all input data to prevent injection attacks:

@RestController
@RequestMapping("/api/v1/users")
public class UserController {
    
    @PostMapping
    public ResponseEntity<UserResponse> createUser(@Valid @RequestBody UserRequest request) {
        // The @Valid annotation triggers validation
        UserResponse user = userService.createUser(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }
}

@Data
public class UserRequest {
    
    @NotBlank(message = "Username is required")
    @Size(min = 3, max = 50, message = "Username must be between 3 and 50 characters")
    @Pattern(regexp = "^[a-zA-Z0-9._-]+$", message = "Username can only contain letters, numbers, dots, underscores, and hyphens")
    private String username;
    
    @NotBlank(message = "Email is required")
    @Email(message = "Email must be valid")
    private String email;
    
    @NotBlank(message = "Password is required")
    @Size(min = 8, message = "Password must be at least 8 characters")
    private String password;
}

Input Sanitization

Sanitize user input to prevent XSS attacks:

@Component
public class InputSanitizer {
    
    private final PolicyFactory policy;
    
    public InputSanitizer() {
        policy = new HtmlPolicyBuilder()
            .allowElements("b", "i", "u", "strong", "em")
            .allowUrlProtocols("https")
            .allowAttributes("href").onElements("a")
            .requireRelNofollowOnLinks()
            .toFactory();
    }
    
    public String sanitize(String input) {
        if (input == null) {
            return null;
        }
        return policy.sanitize(input);
    }
}

@Service
public class ContentService {
    
    private final InputSanitizer sanitizer;
    private final ContentRepository contentRepository;
    
    // Constructor
    
    public Content createContent(ContentRequest request) {
        // Sanitize user-generated content
        String sanitizedTitle = sanitizer.sanitize(request.getTitle());
        String sanitizedBody = sanitizer.sanitize(request.getBody());
        
        Content content = new Content();
        content.setTitle(sanitizedTitle);
        content.setBody(sanitizedBody);
        content.setAuthor(request.getAuthor());
        
        return contentRepository.save(content);
    }
}

Secure File Uploads

File Upload Security

Implement secure file upload handling:

@RestController
@RequestMapping("/api/v1/files")
public class FileController {
    
    private final FileStorageService fileStorageService;
    
    // Constructor
    
    @PostMapping("/upload")
    public ResponseEntity<FileResponse> uploadFile(
            @RequestParam("file") MultipartFile file) {
        
        // Validate file type
        String contentType = file.getContentType();
        if (contentType == null || !isAllowedContentType(contentType)) {
            throw new InvalidFileTypeException("File type not allowed");
        }
        
        // Validate file size
        if (file.getSize() > 5_000_000) { // 5MB limit
            throw new FileTooLargeException("File size exceeds the limit");
        }
        
        // Generate a secure random filename
        String originalFilename = file.getOriginalFilename();
        String fileExtension = getFileExtension(originalFilename);
        String secureFilename = UUID.randomUUID().toString() + fileExtension;
        
        // Store the file
        String storedFilePath = fileStorageService.storeFile(file, secureFilename);
        
        // Return response
        FileResponse response = new FileResponse(
            secureFilename,
            storedFilePath,
            file.getContentType(),
            file.getSize()
        );
        
        return ResponseEntity.ok(response);
    }
    
    private boolean isAllowedContentType(String contentType) {
        List<String> allowedTypes = List.of(
            "image/jpeg",
            "image/png",
            "image/gif",
            "application/pdf",
            "application/msword",
            "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        );
        
        return allowedTypes.contains(contentType);
    }
    
    private String getFileExtension(String filename) {
        if (filename == null) {
            return "";
        }
        
        int dotIndex = filename.lastIndexOf('.');
        if (dotIndex < 0) {
            return "";
        }
        
        return filename.substring(dotIndex);
    }
}

File Storage Service

@Service
public class FileStorageService {
    
    private final Path fileStorageLocation;
    
    @Autowired
    public FileStorageService(@Value("${file.upload-dir}") String uploadDir) {
        this.fileStorageLocation = Paths.get(uploadDir)
            .toAbsolutePath().normalize();
        
        try {
            Files.createDirectories(this.fileStorageLocation);
        } catch (Exception ex) {
            throw new FileStorageException("Could not create the directory where the uploaded files will be stored", ex);
        }
    }
    
    public String storeFile(MultipartFile file, String filename) {
        try {
            // Check if the filename contains invalid characters
            if (filename.contains("..")) {
                throw new FileStorageException("Filename contains invalid path sequence " + filename);
            }
            
            // Copy file to the target location
            Path targetLocation = this.fileStorageLocation.resolve(filename);
            Files.copy(file.getInputStream(), targetLocation, StandardCopyOption.REPLACE_EXISTING);
            
            return targetLocation.toString();
        } catch (IOException ex) {
            throw new FileStorageException("Could not store file " + filename, ex);
        }
    }
}

Rate Limiting

Implement Rate Limiting

Protect your API from abuse with rate limiting:

@Configuration
public class RateLimitingConfig {
    
    @Bean
    public FilterRegistrationBean<RateLimitingFilter> rateLimitingFilter() {
        FilterRegistrationBean<RateLimitingFilter> registrationBean = new FilterRegistrationBean<>();
        
        registrationBean.setFilter(new RateLimitingFilter());
        registrationBean.addUrlPatterns("/api/*");
        
        return registrationBean;
    }
}

public class RateLimitingFilter extends OncePerRequestFilter {
    
    private final Map<String, TokenBucket> buckets = new ConcurrentHashMap<>();
    
    // Rate limit: 10 requests per minute
    private static final int CAPACITY = 10;
    private static final int REFILL_RATE = 10;
    private static final int REFILL_PERIOD_MINUTES = 1;
    
    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {
        
        String clientIp = getClientIp(request);
        TokenBucket tokenBucket = buckets.computeIfAbsent(clientIp, 
            ip -> new TokenBucket(CAPACITY, REFILL_RATE, REFILL_PERIOD_MINUTES));
        
        if (tokenBucket.tryConsume()) {
            filterChain.doFilter(request, response);
        } else {
            response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
            response.getWriter().write("Rate limit exceeded. Please try again later.");
        }
    }
    
    private String getClientIp(HttpServletRequest request) {
        String xForwardedFor = request.getHeader("X-Forwarded-For");
        if (xForwardedFor != null && !xForwardedFor.isEmpty()) {
            return xForwardedFor.split(",")[0].trim();
        }
        return request.getRemoteAddr();
    }
    
    private static class TokenBucket {
        private final int capacity;
        private final int refillRate;
        private final long refillPeriodMillis;
        private int tokens;
        private long lastRefillTimestamp;
        
        public TokenBucket(int capacity, int refillRate, int refillPeriodMinutes) {
            this.capacity = capacity;
            this.refillRate = refillRate;
            this.refillPeriodMillis = refillPeriodMinutes * 60 * 1000;
            this.tokens = capacity;
            this.lastRefillTimestamp = System.currentTimeMillis();
        }
        
        public synchronized boolean tryConsume() {
            refill();
            
            if (tokens > 0) {
                tokens--;
                return true;
            }
            
            return false;
        }
        
        private void refill() {
            long now = System.currentTimeMillis();
            long timeSinceLastRefill = now - lastRefillTimestamp;
            
            if (timeSinceLastRefill >= refillPeriodMillis) {
                long periodsElapsed = timeSinceLastRefill / refillPeriodMillis;
                int tokensToAdd = (int) (periodsElapsed * refillRate);
                
                tokens = Math.min(capacity, tokens + tokensToAdd);
                lastRefillTimestamp = now;
            }
        }
    }
}

Secure Communication

HTTPS Configuration

Enforce HTTPS for all communications:

# application.yml
server:
  port: 8443
  ssl:
    key-store: classpath:keystore.p12
    key-store-password: ${KEY_STORE_PASSWORD}
    key-store-type: PKCS12
    key-alias: tomcat
  servlet:
    session:
      cookie:
        secure: true
        http-only: true
        same-site: strict

@Configuration
public class HttpsConfig {
    
    @Bean
    public ServletWebServerFactory servletContainer() {
        TomcatServletWebServerFactory tomcat = new TomcatServletWebServerFactory() {
            @Override
            protected void postProcessContext(Context context) {
                SecurityConstraint securityConstraint = new SecurityConstraint();
                securityConstraint.setUserConstraint("CONFIDENTIAL");
                SecurityCollection collection = new SecurityCollection();
                collection.addPattern("/*");
                securityConstraint.addCollection(collection);
                context.addConstraint(securityConstraint);
            }
        };
        
        tomcat.addAdditionalTomcatConnectors(redirectConnector());
        return tomcat;
    }
    
    private Connector redirectConnector() {
        Connector connector = new Connector("org.apache.coyote.http11.Http11NioProtocol");
        connector.setScheme("http");
        connector.setPort(8080);
        connector.setSecure(false);
        connector.setRedirectPort(8443);
        return connector;
    }
}

Logging and Monitoring

Security Event Logging

Log security-related events for auditing:

@Component
public class SecurityEventLogger {
    
    private static final Logger log = LoggerFactory.getLogger(SecurityEventLogger.class);
    
    public void logAuthenticationSuccess(String username) {
        log.info("Authentication success for user: {}", username);
    }
    
    public void logAuthenticationFailure(String username, String reason) {
        log.warn("Authentication failure for user: {}, reason: {}", username, reason);
    }
    
    public void logAccessDenied(String username, String resource) {
        log.warn("Access denied for user: {} to resource: {}", username, resource);
    }
    
    public void logSecurityEvent(String event, String username, String details) {
        log.info("Security event: {}, user: {}, details: {}", event, username, details);
    }
}

@Component
public class AuthenticationEventListener {
    
    private final SecurityEventLogger securityEventLogger;
    
    // Constructor
    
    @EventListener
    public void onAuthenticationSuccess(AuthenticationSuccessEvent event) {
        String username = ((UserDetails) event.getAuthentication().getPrincipal()).getUsername();
        securityEventLogger.logAuthenticationSuccess(username);
    }
    
    @EventListener
    public void onAuthenticationFailure(AuthenticationFailureBadCredentialsEvent event) {
        String username = event.getAuthentication().getName();
        securityEventLogger.logAuthenticationFailure(username, "Bad credentials");
    }
    
    @EventListener
    public void onAccessDenied(AccessDeniedEvent event) {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        String username = auth != null ? auth.getName() : "anonymous";
        securityEventLogger.logAccessDenied(username, event.getSource().toString());
    }
}

Security Monitoring

Implement security monitoring with Spring Boot Actuator:

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,auditevents
  endpoint:
    health:
      show-details: when_authorized
  auditevents:
    enabled: true

@Configuration
public class ActuatorSecurityConfig {
    
    @Bean
    public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/actuator/**")
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/actuator/health").permitAll()
                .requestMatchers("/actuator/info").permitAll()
                .requestMatchers("/actuator/**").hasRole("ADMIN")
            )
            .httpBasic(Customizer.withDefaults());
            
        return http.build();
    }
}

Dependency Management

Keep Dependencies Updated

Regularly update dependencies to patch security vulnerabilities:

<!-- Use dependency management for consistent versions -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Dependency Vulnerability Scanning

Use tools like OWASP Dependency Check to scan for vulnerabilities:

<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>8.2.1</version>
    <executions>
        <execution>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Conclusion

Securing Spring Boot applications requires a multi-layered approach that addresses authentication, authorization, data validation, secure communication, and more. By implementing the best practices outlined in this guide, you can significantly reduce the risk of security vulnerabilities in your applications.

Remember that security is an ongoing process, not a one-time task. Regularly review and update your security measures, stay informed about new vulnerabilities and threats, and conduct security testing to ensure your applications remain protected.

Key takeaways:

• Implement proper authentication and authorization
• Validate and sanitize all input
• Use HTTPS for all communications
• Keep dependencies updated
• Log security events for auditing
• Implement rate limiting to prevent abuse
• Follow the principle of least privilege

By following these best practices, you can build Spring Boot applications that are not only functional but also secure and resilient against common security threats.