JWT Authentication with Spring Boot: A Professional Guide to Stateless Security

package io.thecodeforge.security;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.io.Decoders;
import io.jsonwebtoken.security.Keys;

import java.security.Key;
import java.util.Date;

public class JwtStructureDemo {

    // Generated with: openssl rand -base64 32
    // In production this comes from ${JWT_SECRET} environment variable — never hardcoded
    private static final String SECRET_KEY = "dGhpcyBpcyBhIDI1NiBiaXQgc2VjcmV0IGtleSBmb3Igand0IHNpZ25pbmc=";

    public static void main(String[] args) {

        Key signingKey = Keys.hmacShaKeyFor(Decoders.BASE64.decode(SECRET_KEY));

        // Build a token with standard + custom claims
        String token = Jwts.builder()
                .setSubject("alice@thecodeforge.io")         // who the token represents
                .setIssuer("thecodeforge-auth-service")      // who issued it
                .setAudience("thecodeforge-api")             // intended recipient
                .setIssuedAt(new Date())
                .setExpiration(new Date(System.currentTimeMillis() + 3600000)) // 1 hour
                .setId("tok-" + System.currentTimeMillis()) // unique ID for blacklisting
                .claim("roles", "ROLE_ADMIN,ROLE_USER")      // custom claim — authorization
                .claim("tenant_id", "tenant-001")           // custom claim — multi-tenancy
                .signWith(signingKey, SignatureAlgorithm.HS256)
                .compact();

        System.out.println("Token: " + token);
        System.out.println();

        // Parse and read claims — this is what the filter does on every request
        Claims claims = Jwts.parserBuilder()
                .setSigningKey(signingKey)
                .build()
                .parseClaimsJws(token)
                .getBody();

        System.out.println("Subject:   " + claims.getSubject());
        System.out.println("Issuer:    " + claims.getIssuer());
        System.out.println("Expires:   " + claims.getExpiration());
        System.out.println("Token ID:  " + claims.getId());
        System.out.println("Roles:     " + claims.get("roles"));
        System.out.println("Tenant:    " + claims.get("tenant_id"));
        System.out.println();

        // Demonstrate tamper detection — this is the entire security guarantee
        String tamperedToken = token.substring(0, token.length() - 5) + "XXXXX";
        try {
            Jwts.parserBuilder()
                    .setSigningKey(signingKey)
                    .build()
                    .parseClaimsJws(tamperedToken);
        } catch (Exception e) {
            System.out.println("Tampered token rejected: " + e.getClass().getSimpleName());
            System.out.println("Message: " + e.getMessage());
        }
    }
}

package io.thecodeforge.security;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.io.Decoders;
import io.jsonwebtoken.security.Keys;

import java.security.Key;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.util.Date;

public class AlgorithmComparison {

    public static void main(String[] args) throws Exception {

        // ========== HS256: Symmetric — one key signs AND verifies ==========
        String sharedSecret = "dGhpcyBpcyBhIDI1NiBiaXQgc2VjcmV0IGtleSBmb3Igand0IHNpZ25pbmc=";
        Key hmacKey = Keys.hmacShaKeyFor(Decoders.BASE64.decode(sharedSecret));

        String hs256Token = Jwts.builder()
                .setSubject("alice@thecodeforge.io")
                .setIssuer("thecodeforge-auth")
                .setExpiration(new Date(System.currentTimeMillis() + 3600000))
                .signWith(hmacKey, SignatureAlgorithm.HS256)
                .compact();

        // Same key used to verify — every service that validates needs this secret
        Claims hs256Claims = Jwts.parserBuilder()
                .setSigningKey(hmacKey)
                .build()
                .parseClaimsJws(hs256Token)
                .getBody();

        System.out.println("HS256 subject: " + hs256Claims.getSubject());
        System.out.println("HS256 token length: " + hs256Token.length() + " chars");
        System.out.println();

        // ========== RS256: Asymmetric — private key signs, public key verifies ==========
        // In production: load from a PEM file or secrets manager, don't generate each time
        KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("RSA");
        keyPairGen.initialize(2048);
        KeyPair rsaKeyPair = keyPairGen.generateKeyPair();
        PrivateKey privateKey = rsaKeyPair.getPrivate(); // stays on auth server only
        PublicKey publicKey = rsaKeyPair.getPublic();    // distributed to all resource servers

        String rs256Token = Jwts.builder()
                .setSubject("alice@thecodeforge.io")
                .setIssuer("thecodeforge-auth")
                .setExpiration(new Date(System.currentTimeMillis() + 3600000))
                .signWith(privateKey, SignatureAlgorithm.RS256)
                .compact();

        // Public key verifies — a compromised resource server cannot forge tokens
        Claims rs256Claims = Jwts.parserBuilder()
                .setSigningKey(publicKey)
                .build()
                .parseClaimsJws(rs256Token)
                .getBody();

        System.out.println("RS256 subject: " + rs256Claims.getSubject());
        System.out.println("RS256 token length: " + rs256Token.length() + " chars");

        // Attempt to use public key for signing — this fails with a meaningful error
        try {
            Jwts.builder()
                    .setSubject("attacker@evil.io")
                    .signWith(publicKey, SignatureAlgorithm.RS256)
                    .compact();
        } catch (Exception e) {
            System.out.println("\nCannot sign with public key: " + e.getClass().getSimpleName());
        }
    }
}

<dependencies>
    <!-- Web layer: REST controllers, embedded Tomcat -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring Security: filter chain, authentication, authorization -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>

    <!-- JJWT: all three artifacts are REQUIRED — api alone is just interfaces -->
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-api</artifactId>
        <version>0.12.5</version>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-impl</artifactId>
        <version>0.12.5</version>
        <scope>runtime</scope> <!-- implementation loaded at runtime via SPI -->
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-jackson</artifactId>
        <version>0.12.5</version>
        <scope>runtime</scope> <!-- JSON serialization of claims -->
    </dependency>

    <!-- JPA + H2 for the user repository (swap H2 for PostgreSQL in production) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <scope>runtime</scope>
    </dependency>

    <!-- Lombok: reduces boilerplate for entities and services -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <!-- Validation: @Valid on request bodies -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>

    <!-- Actuator: exposes /actuator/health for the SecurityHealthIndicator -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

application:
  security:
    jwt:
      # In production: set JWT_SECRET environment variable — never use the fallback value
      # Generate with: openssl rand -base64 32
      # Must decode to at least 32 bytes — JJWT enforces this with WeakKeyException
      secret-key: ${JWT_SECRET:dGhpcyBpcyBhIHZlcnkgc2VjdXJlIHNlY3JldCBrZXkgZm9yIGp3dA==}
      expiration: 900000          # 15 minutes — access token
      refresh-token:
        expiration: 604800000     # 7 days — refresh token

spring:
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: false               # set to true in dev only — leaks query structure in prod logs
  datasource:
    url: jdbc:h2:mem:testdb      # replace with PostgreSQL in production
    driver-class-name: org.h2.Driver

management:
  endpoints:
    web:
      exposure:
        include: health           # expose only health — never expose env or beans in production
  endpoint:
    health:
      show-details: when-authorized

logging:
  level:
    io.thecodeforge.security: DEBUG   # remove DEBUG in production
    org.springframework.security: INFO

package io.thecodeforge.security;

import jakarta.persistence.*;
import lombok.*;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;

import java.util.Collection;
import java.util.List;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Table(name = "users",
       indexes = @Index(name = "idx_users_email", columnList = "email")) // email lookup is hot path
public class User implements UserDetails {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @Column(unique = true, nullable = false, length = 255)
    private String email;

    @Column(nullable = false, length = 100)
    private String firstname;

    @Column(length = 100)
    private String lastname;

    @Column(nullable = false, length = 60) // BCrypt output is always 60 characters
    private String password;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false, length = 20)
    private Role role;

    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        // In practice you may want to return multiple authorities for fine-grained RBAC
        return List.of(new SimpleGrantedAuthority(role.name()));
    }

    @Override
    public String getUsername() {
        return email; // email is the unique identifier used for authentication
    }

    @Override
    public String getPassword() {
        return password;
    }

    // For production systems, drive these from database columns rather than returning true
    @Override public boolean isAccountNonExpired() { return true; }
    @Override public boolean isAccountNonLocked() { return true; }
    @Override public boolean isCredentialsNonExpired() { return true; }
    @Override public boolean isEnabled() { return true; }
}

package io.thecodeforge.security;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.io.Decoders;
import io.jsonwebtoken.security.Keys;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.stereotype.Service;

import java.security.Key;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.function.Function;

@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;

    // Generate a standard access token with no extra claims
    public String generateToken(UserDetails userDetails) {
        return buildToken(new HashMap<>(), userDetails, jwtExpiration);
    }

    // Generate a refresh token — longer TTL, same signing key, no extra claims
    public String generateRefreshToken(UserDetails userDetails) {
        return buildToken(new HashMap<>(), userDetails, refreshExpiration);
    }

    // Generate an access token with application-specific extra claims (roles, tenant_id, etc.)
    public String generateToken(Map<String, Object> extraClaims, UserDetails userDetails) {
        return buildToken(extraClaims, userDetails, jwtExpiration);
    }

    private String buildToken(
            Map<String, Object> extraClaims,
            UserDetails userDetails,
            long expiration
    ) {
        return Jwts.builder()
                .setClaims(extraClaims)                         // custom claims first — setSubject overwrites sub if set in claims
                .setSubject(userDetails.getUsername())          // email is the subject
                .setIssuer("thecodeforge-auth")
                .setIssuedAt(new Date(System.currentTimeMillis()))
                .setExpiration(new Date(System.currentTimeMillis() + expiration))
                .signWith(getSignInKey(), SignatureAlgorithm.HS256)
                .compact();
    }

    // Called by the filter on every authenticated request
    public boolean isTokenValid(String token, UserDetails userDetails) {
        final String username = extractUsername(token);
        return username.equals(userDetails.getUsername()) && !isTokenExpired(token);
    }

    public boolean isTokenExpired(String token) {
        return extractExpiration(token).before(new Date());
    }

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

    public Date extractExpiration(String token) {
        return extractClaim(token, Claims::getExpiration);
    }

    // Generic claim extractor — pass any Claims method reference
    public <T> T extractClaim(String token, Function<Claims, T> claimsResolver) {
        final Claims claims = extractAllClaims(token);
        return claimsResolver.apply(claims);
    }

    private Claims extractAllClaims(String token) {
        // This is where signature verification happens
        // Throws SignatureException, ExpiredJwtException, MalformedJwtException on failure
        return Jwts.parserBuilder()
                .setSigningKey(getSignInKey())
                .build()
                .parseClaimsJws(token)
                .getBody();
    }

    private Key getSignInKey() {
        byte[] keyBytes = Decoders.BASE64.decode(secretKey);
        // Keys.hmacShaKeyFor throws WeakKeyException if keyBytes.length < 32
        return Keys.hmacShaKeyFor(keyBytes);
    }
}

package io.thecodeforge.security;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.lang.NonNull;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

@Slf4j
@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtService jwtService;
    private final UserDetailsService userDetailsService;

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

        final String authHeader = request.getHeader("Authorization");

        // No token present — skip silently and let Spring Security handle authorization
        // This is the CORRECT behavior for public endpoints like /auth/login
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            filterChain.doFilter(request, response);
            return;
        }

        final String jwt = authHeader.substring(7); // strip "Bearer " prefix
        final String username;

        try {
            username = jwtService.extractUsername(jwt);
        } catch (Exception e) {
            // Token is expired, malformed, or has an invalid signature
            // Log at debug level — this is normal for expired tokens, not an error
            log.debug("JWT extraction failed for request {}: {}", request.getRequestURI(), e.getMessage());
            filterChain.doFilter(request, response);
            return;
        }

        // Only authenticate if we have a username and no authentication is set yet
        // The null check prevents re-authenticating an already-authenticated request
        if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {

            UserDetails userDetails = userDetailsService.loadUserByUsername(username);

            if (jwtService.isTokenValid(jwt, userDetails)) {
                UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(
                        userDetails,
                        null,                           // credentials null — we use the JWT, not a password
                        userDetails.getAuthorities()    // roles from UserDetails, loaded from database
                );
                authToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                SecurityContextHolder.getContext().setAuthentication(authToken);

                log.debug("Authenticated user '{}' for request {}", username, request.getRequestURI());
            }
        }

        filterChain.doFilter(request, response);
    }
}

package io.thecodeforge.security;

import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationProvider;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@Configuration
@EnableWebSecurity
@EnableMethodSecurity   // Required for @PreAuthorize — without this, annotations are silently ignored
@RequiredArgsConstructor
public class SecurityConfig {

    private final JwtAuthenticationFilter jwtAuthFilter;
    private final AuthenticationProvider authenticationProvider;
    private final JwtAuthenticationEntryPoint authEntryPoint;
    private final JwtAccessDeniedHandler accessDeniedHandler;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                // Disable CSRF — stateless APIs use Authorization headers, not cookies
                // CSRF attacks target cookie-based auth; JWT via header is not vulnerable
                .csrf(AbstractHttpConfigurer::disable)

                // Authorization rules — order matters, more specific rules first
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/api/v1/auth/**").permitAll()   // login, register, refresh
                        .requestMatchers("/actuator/health").permitAll()  // health check for load balancers
                        .anyRequest().authenticated()                     // everything else requires JWT
                )

                // Never create a HttpSession — JWT is the only auth mechanism
                .sessionManagement(session -> session
                        .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                )

                // Custom exception handlers — JSON responses instead of Spring's HTML error pages
                .exceptionHandling(ex -> ex
                        .authenticationEntryPoint(authEntryPoint)      // 401 handler
                        .accessDeniedHandler(accessDeniedHandler)       // 403 handler
                )

                .authenticationProvider(authenticationProvider)

                // JwtAuthenticationFilter runs before UsernamePasswordAuthenticationFilter
                // This ensures JWT tokens are processed before any form-login logic
                .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }
}

package io.thecodeforge.security;

import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

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

    private final AuthenticationManager authenticationManager;
    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;
    private final JwtService jwtService;

    @PostMapping("/register")
    public ResponseEntity<AuthenticationResponse> register(@Valid @RequestBody RegisterRequest request) {
        // Check for duplicate email before creating — return 400 with a clear message
        if (userRepository.findByEmail(request.getEmail()).isPresent()) {
            return ResponseEntity.badRequest().body(
                    AuthenticationResponse.builder().error("Email already registered").build()
            );
        }

        User user = User.builder()
                .email(request.getEmail())
                .firstname(request.getFirstname())
                .lastname(request.getLastname())
                .password(passwordEncoder.encode(request.getPassword())) // BCrypt hash
                .role(Role.USER)  // new users are USER by default — admins are promoted separately
                .build();
        userRepository.save(user);

        return ResponseEntity.ok(AuthenticationResponse.builder()
                .accessToken(jwtService.generateToken(user))
                .refreshToken(jwtService.generateRefreshToken(user))
                .build());
    }

    @PostMapping("/login")
    public ResponseEntity<AuthenticationResponse> login(@Valid @RequestBody AuthenticationRequest request) {
        try {
            // authenticate() throws BadCredentialsException if email or password is wrong
            authenticationManager.authenticate(
                    new UsernamePasswordAuthenticationToken(request.getEmail(), request.getPassword())
            );

            User user = userRepository.findByEmail(request.getEmail()).orElseThrow();

            return ResponseEntity.ok(AuthenticationResponse.builder()
                    .accessToken(jwtService.generateToken(user))
                    .refreshToken(jwtService.generateRefreshToken(user))
                    .build());

        } catch (BadCredentialsException e) {
            // Generic message — never reveal which field was wrong
            // 'User not found' vs 'Wrong password' enables email enumeration attacks
            return ResponseEntity.status(401).body(
                    AuthenticationResponse.builder().error("Invalid email or password").build()
            );
        }
    }

    @PostMapping("/refresh")
    public ResponseEntity<AuthenticationResponse> refresh(@RequestBody Map<String, String> request) {
        String refreshToken = request.get("refreshToken");

        if (refreshToken == null || refreshToken.isBlank()) {
            return ResponseEntity.badRequest().body(
                    AuthenticationResponse.builder().error("Refresh token required").build()
            );
        }

        try {
            String username = jwtService.extractUsername(refreshToken);
            User user = userRepository.findByEmail(username).orElseThrow();

            if (jwtService.isTokenValid(refreshToken, user)) {
                // Issue a new access token — refresh token is not rotated in this implementation
                return ResponseEntity.ok(AuthenticationResponse.builder()
                        .accessToken(jwtService.generateToken(user))
                        .build());
            }

            return ResponseEntity.status(401).body(
                    AuthenticationResponse.builder().error("Refresh token is invalid or expired").build()
            );

        } catch (Exception e) {
            return ResponseEntity.status(401).body(
                    AuthenticationResponse.builder().error("Refresh token is invalid or expired").build()
            );
        }
    }
}

package io.thecodeforge.controller;

import org.springframework.http.ResponseEntity;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.Authentication;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api/v1")
public class AuthorizationDemoController {

    // Any authenticated user — no role requirement
    @GetMapping("/profile")
    public ResponseEntity<Map<String, String>> profile(Authentication auth) {
        return ResponseEntity.ok(Map.of(
                "username", auth.getName(),
                "authorities", auth.getAuthorities().toString()
        ));
    }

    // Admin only — hasAuthority uses the exact string, no ROLE_ prefix added automatically
    @GetMapping("/admin/dashboard")
    @PreAuthorize("hasAuthority('ROLE_ADMIN')")
    public ResponseEntity<Map<String, String>> adminDashboard() {
        return ResponseEntity.ok(Map.of("message", "Admin dashboard"));
    }

    // Multiple roles accepted — either ROLE_USER or ROLE_ADMIN can access
    @GetMapping("/orders")
    @PreAuthorize("hasAnyAuthority('ROLE_USER', 'ROLE_ADMIN')")
    public ResponseEntity<Map<String, String>> orders() {
        return ResponseEntity.ok(Map.of("message", "Your orders"));
    }

    // Ownership check — user can access their own data, admin can access any
    // #userId binds the @PathVariable value into the SpEL expression
    @GetMapping("/users/{userId}/data")
    @PreAuthorize("hasAuthority('ROLE_ADMIN') or #userId == authentication.principal.id")
    public ResponseEntity<Map<String, String>> userData(
            @PathVariable Integer userId,
            Authentication auth
    ) {
        return ResponseEntity.ok(Map.of(
                "requestedUser", String.valueOf(userId),
                "requestingUser", auth.getName()
        ));
    }

    // Combining method-level and URL-level security is intentional
    // URL level: /api/v1/** -> any authenticated user
    // Method level: hasAuthority('ROLE_ADMIN') -> further restricted
    @DeleteMapping("/admin/users/{userId}")
    @PreAuthorize("hasAuthority('ROLE_ADMIN')")
    public ResponseEntity<Void> deleteUser(@PathVariable Integer userId) {
        // Admin-only destructive operation
        return ResponseEntity.noContent().build();
    }
}

package io.thecodeforge.security;

import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.MediaType;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;

import java.io.IOException;
import java.time.Instant;
import java.util.LinkedHashMap;
import java.util.Map;

@Component
public class JwtAuthenticationEntryPoint implements AuthenticationEntryPoint {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public void commence(
            HttpServletRequest request,
            HttpServletResponse response,
            AuthenticationException authException
    ) throws IOException {
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);

        // Ordered map so the JSON output has a consistent field order
        Map<String, Object> body = new LinkedHashMap<>();
        body.put("status", 401);
        body.put("error", "Unauthorized");
        body.put("message", "Authentication required. Provide a valid JWT in the Authorization header.");
        body.put("path", request.getRequestURI());
        body.put("timestamp", Instant.now().toString());

        objectMapper.writeValue(response.getOutputStream(), body);
    }
}

package io.thecodeforge.security;

import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Service;

import java.util.Arrays;
import java.util.Optional;

@Service
public class CookieTokenService {

    private static final String REFRESH_TOKEN_COOKIE = "refresh_token";
    private static final String REFRESH_TOKEN_PATH = "/api/v1/auth/refresh";
    private static final int SEVEN_DAYS_SECONDS = 7 * 24 * 60 * 60;

    public void setRefreshTokenCookie(HttpServletResponse response, String refreshToken) {
        Cookie cookie = new Cookie(REFRESH_TOKEN_COOKIE, refreshToken);

        cookie.setHttpOnly(true);                        // JavaScript cannot access this cookie
        cookie.setSecure(true);                          // HTTPS only — never sent over HTTP
        cookie.setAttribute("SameSite", "Strict");       // not sent on cross-origin requests — CSRF protection
        cookie.setPath(REFRESH_TOKEN_PATH);              // scoped to refresh endpoint only — not sent with every request
        cookie.setMaxAge(SEVEN_DAYS_SECONDS);            // matches refresh token TTL in JwtService

        response.addCookie(cookie);
    }

    public Optional<String> extractRefreshTokenFromCookie(HttpServletRequest request) {
        if (request.getCookies() == null) {
            return Optional.empty();
        }
        return Arrays.stream(request.getCookies())
                .filter(c -> REFRESH_TOKEN_COOKIE.equals(c.getName()))
                .map(Cookie::getValue)
                .findFirst();
    }

    public void clearRefreshTokenCookie(HttpServletResponse response) {
        Cookie cookie = new Cookie(REFRESH_TOKEN_COOKIE, "");
        cookie.setHttpOnly(true);
        cookie.setSecure(true);
        cookie.setAttribute("SameSite", "Strict");
        cookie.setPath(REFRESH_TOKEN_PATH);
        cookie.setMaxAge(0); // tells the browser to delete the cookie immediately
        response.addCookie(cookie);
    }
}

package io.thecodeforge.health;

import io.jsonwebtoken.io.Decoders;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

/**
 * Validates JWT configuration at startup.
 * Exposed via GET /actuator/health — load balancers use this to gate traffic.
 * A misconfigured JWT key is detected before the first user tries to log in.
 */
@Component
public class JwtSecurityHealthIndicator implements HealthIndicator {

    // Known default/test keys that must never reach production
    private static final String DEV_FALLBACK_PREFIX = "dGhpcyBpcyBhIHZlcnkgc2VjdXJlIHNlY3JldCBrZXkgZm9yIGp3dA";

    @Value("${application.security.jwt.secret-key}")
    private String secretKey;

    @Value("${application.security.jwt.expiration}")
    private long accessTokenTtl;

    @Value("${application.security.jwt.refresh-token.expiration}")
    private long refreshTokenTtl;

    @Override
    public Health health() {
        try {
            if (secretKey == null || secretKey.isBlank()) {
                return Health.down()
                        .withDetail("error", "JWT secret key is not configured")
                        .build();
            }

            if (secretKey.startsWith(DEV_FALLBACK_PREFIX)) {
                return Health.down()
                        .withDetail("error", "JWT secret key is the development fallback — set JWT_SECRET environment variable")
                        .build();
            }

            byte[] keyBytes = Decoders.BASE64.decode(secretKey);
            if (keyBytes.length < 32) {
                return Health.down()
                        .withDetail("error", "JWT secret key is too short for HS256")
                        .withDetail("required_bits", 256)
                        .withDetail("actual_bits", keyBytes.length * 8)
                        .build();
            }

            if (accessTokenTtl < 300_000) { // less than 5 minutes
                return Health.down()
                        .withDetail("error", "Access token TTL is too short (< 5 minutes)")
                        .build();
            }

            if (accessTokenTtl > 86_400_000) { // more than 24 hours
                return Health.down()
                        .withDetail("error", "Access token TTL is too long (> 24 hours) — use a refresh token instead")
                        .build();
            }

            if (refreshTokenTtl <= accessTokenTtl) {
                return Health.down()
                        .withDetail("error", "Refresh token TTL must be longer than access token TTL")
                        .build();
            }

            return Health.up()
                    .withDetail("key_bits", keyBytes.length * 8)
                    .withDetail("access_token_ttl_minutes", accessTokenTtl / 60_000)
                    .withDetail("refresh_token_ttl_days", refreshTokenTtl / 86_400_000)
                    .build();

        } catch (Exception e) {
            return Health.down()
                    .withDetail("error", "JWT configuration is invalid: " + e.getMessage())
                    .build();
        }
    }
}