spring-boot-security-jwt

SKILL.md

Spring Boot JWT Security

JWT authentication and authorization patterns for Spring Boot 3.5.x using Spring Security 6.x and JJWT. Covers token generation, validation, refresh strategies, RBAC/ABAC, and OAuth2 integration.

Overview

This skill provides implementation patterns for stateless JWT authentication in Spring Boot applications. It covers the complete authentication flow including token generation with JJWT 0.12.6, Bearer/cookie-based authentication, refresh token rotation, and method-level authorization with @PreAuthorize expressions.

Key capabilities:

Access and refresh token generation with configurable expiration

Bearer token and HttpOnly cookie authentication strategies

Integration with Spring Data JPA and OAuth2 providers

RBAC with role/permission-based @PreAuthorize rules

Token revocation and blacklisting for logout/rotation

When to Use
Activate when user requests involve:

"Implement JWT authentication", "secure REST API with tokens"

"Spring Security 6.x configuration", "SecurityFilterChain setup"

"Role-based access control", "RBAC", `@PreAuthorize`

"Refresh token", "token rotation", "token revocation"

"OAuth2 integration", "social login", "Google/GitHub auth"

"Stateless authentication", "SPA backend security"

"JWT filter", "OncePerRequestFilter", "Bearer token"

"Cookie-based JWT", "HttpOnly cookie"

"Permission-based access control", "custom PermissionEvaluator"

Quick Reference

Dependencies (JJWT 0.12.6)

Artifact
Scope

spring-boot-starter-security
compile

spring-boot-starter-oauth2-resource-server
compile

io.jsonwebtoken:jjwt-api:0.12.6
compile

io.jsonwebtoken:jjwt-impl:0.12.6
runtime

io.jsonwebtoken:jjwt-jackson:0.12.6
runtime

spring-security-test
test

See references/jwt-quick-reference.md for Maven and Gradle snippets.

Key Configuration Properties

Property
Example Value
Notes

jwt.secret
${JWT_SECRET}
Min 256 bits, never hardcode

jwt.access-token-expiration
900000
15 min in milliseconds

jwt.refresh-token-expiration
604800000
7 days in milliseconds

jwt.issuer
my-app
Validated on every token

jwt.cookie-name
jwt-token
For cookie-based auth

jwt.cookie-http-only
true
Always true in production

jwt.cookie-secure
true
Always true with HTTPS

Authorization Annotations

Annotation
Example

@PreAuthorize("hasRole('ADMIN')")
Role check

@PreAuthorize("hasAuthority('USER_READ')")
Permission check

@PreAuthorize("hasPermission(#id, 'Doc', 'READ')")
Domain object check

@PreAuthorize("@myService.canAccess(#id)")
Spring bean check

Instructions

Step 1 — Add Dependencies

Include spring-boot-starter-security, spring-boot-starter-oauth2-resource-server, and the three JJWT artifacts in your build file. See references/jwt-quick-reference.md for exact Maven/Gradle snippets.

Step 2 — Configure application.yml

jwt:
  secret: ${JWT_SECRET:change-me-min-32-chars-in-production}
  access-token-expiration: 900000
  refresh-token-expiration: 604800000
  issuer: my-app
  cookie-name: jwt-token
  cookie-http-only: true
  cookie-secure: false   # true in production

See references/jwt-complete-configuration.md for the full properties reference.

Step 3 — Implement JwtService

Core operations: generate access token, generate refresh token, extract username, validate token.

@Service
public class JwtService {

    public String generateAccessToken(UserDetails userDetails) {
        return Jwts.builder()
            .subject(userDetails.getUsername())
            .issuer(issuer)
            .issuedAt(new Date())
            .expiration(new Date(System.currentTimeMillis() + accessTokenExpiration))
            .claim("authorities", getAuthorities(userDetails))
            .signWith(getSigningKey())
            .compact();
    }

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

See references/jwt-complete-configuration.md for the complete JwtService including key management and claim extraction.

Step 4 — Create JwtAuthenticationFilter

Extend OncePerRequestFilter to extract a JWT from the Authorization: Bearer header (or HttpOnly cookie), validate it, and set the SecurityContext.

@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
            HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
        String authHeader = request.getHeader("Authorization");
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            chain.doFilter(request, response);
            return;
        }
        String jwt = authHeader.substring(7);
        String username = jwtService.extractUsername(jwt);
        if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {
            UserDetails userDetails = userDetailsService.loadUserByUsername(username);
            if (jwtService.isTokenValid(jwt, userDetails)) {
                UsernamePasswordAuthenticationToken authToken =
                    new UsernamePasswordAuthenticationToken(
                        userDetails, null, userDetails.getAuthorities());
                authToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                SecurityContextHolder.getContext().setAuthentication(authToken);
            }
        }
        chain.doFilter(request, response);
    }
}

See references/configuration.md for the cookie-based variant.

Step 5 — Configure SecurityFilterChain

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(AbstractHttpConfigurer::disable)
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**", "/swagger-ui/**").permitAll()
                .anyRequest().authenticated()
            )
            .authenticationProvider(authenticationProvider)
            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class)
            .build();
    }
}

See references/jwt-complete-configuration.md for CORS, logout handler, and OAuth2 login integration.

Step 6 — Create Authentication Endpoints

Expose /register, /authenticate, /refresh, and /logout via @RestController. Return accessToken + refreshToken in the response body (and optionally set an HttpOnly cookie).

See references/examples.md for the complete AuthenticationController and AuthenticationService.

Step 7 — Implement Refresh Token Strategy

Store refresh tokens in the database with user_id, expiry_date, revoked, and expired columns. On /refresh, verify the stored token, revoke it, and issue a new pair (token rotation).

See references/token-management.md for RefreshToken entity, rotation logic, and Redis-based blacklisting.

Step 8 — Add Authorization Rules

Use @EnableMethodSecurity and @PreAuthorize annotations for fine-grained control:

@PreAuthorize("hasRole('ADMIN')")
public Page<UserResponse> getAllUsers(Pageable pageable) { ... }

@PreAuthorize("hasPermission(#documentId, 'Document', 'READ')")
public Document getDocument(Long documentId) { ... }

See references/authorization-patterns.md for RBAC entity model, PermissionEvaluator, and ABAC patterns.

Step 9 — Write Security Tests

@SpringBootTest
@AutoConfigureMockMvc
class AuthControllerTest {

    @Test
    void shouldDenyAccessWithoutToken() throws Exception {
        mockMvc.perform(get("/api/orders"))
            .andExpect(status().isUnauthorized());
    }

    @Test
    @WithMockUser(roles = "ADMIN")
    void shouldAllowAdminAccess() throws Exception {
        mockMvc.perform(get("/api/admin/users"))
            .andExpect(status().isOk());
    }
}

See references/testing.md and references/jwt-testing-guide.md for full test suites, Testcontainers setup, and a security test checklist.

Best Practices

Token Security

Use minimum 256-bit secret keys — load from environment variables, never hardcode

Set short access token lifetimes (15 min); use refresh tokens for longer sessions

Implement token rotation: revoke old refresh token when issuing a new one

Use jti (JWT ID) claim for blacklisting on logout

Cookie vs Bearer Header

Prefer HttpOnly cookies for browser clients (XSS-safe)

Use Authorization: Bearer header for mobile/API clients

Set Secure, SameSite=Lax or Strict on cookies in production

Spring Security 6.x

Use SecurityFilterChain bean — never extend WebSecurityConfigurerAdapter

Disable CSRF only for stateless APIs; keep it enabled for session-based flows

Use @EnableMethodSecurity instead of deprecated @EnableGlobalMethodSecurity

Validate iss and aud claims; reject tokens from untrusted issuers

Performance

Cache UserDetails with @Cacheable to avoid DB lookup on every request

Cache signing key derivation (avoid re-computing HMAC key per request)

Use Redis for refresh token storage at scale

What NOT to Do

Do not store sensitive data (passwords, PII) in JWT claims — claims are only signed, not encrypted

Do not issue tokens with infinite lifetime

Do not accept tokens without validating signature and expiration

Do not share signing keys across environments

Examples

Basic Authentication Flow

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

    private final AuthService authService;

    @PostMapping("/authenticate")
    public ResponseEntity<AuthResponse> authenticate(
            @RequestBody LoginRequest request) {
        return ResponseEntity.ok(authService.authenticate(request));
    }

    @PostMapping("/refresh")
    public ResponseEntity<AuthResponse> refresh(@RequestBody RefreshRequest request) {
        return ResponseEntity.ok(authService.refreshToken(request.refreshToken()));
    }

    @PostMapping("/logout")
    public ResponseEntity<Void> logout() {
        authService.logout();
        return ResponseEntity.ok().build();
    }
}

JWT Authorization on Controller Method

@RestController
@RequestMapping("/api/admin")
@PreAuthorize("hasRole('ADMIN')")
public class AdminController {

    @GetMapping("/users")
    public ResponseEntity<List<UserResponse>> getAllUsers() {
        return ResponseEntity.ok(adminService.getAllUsers());
    }
}

See references/examples.md for complete entity models and service implementations.

References

File
Content

references/jwt-quick-reference.md
Dependencies, minimal service, common patterns

references/jwt-complete-configuration.md
Full config: properties, SecurityFilterChain, JwtService, OAuth2 RS

references/configuration.md
JWT config beans, CORS, CSRF, error handling, session options

references/examples.md
Complete application setup: controllers, services, entities

references/authorization-patterns.md
RBAC/ABAC entity model, PermissionEvaluator, SpEL expressions

references/token-management.md
Refresh token entity, rotation, blacklisting with Redis

references/testing.md
Unit and MockMvc tests, test utilities

references/jwt-testing-guide.md
Testcontainers, load testing, security test checklist

references/security-hardening.md
Security headers, HSTS, rate limiting, audit logging

references/performance-optimization.md
Caffeine cache config, async validation, connection pooling

references/oauth2-integration.md
Google/GitHub OAuth2 login, OAuth2UserService

references/microservices-security.md
Inter-service JWT propagation, resource server config

references/migration-spring-security-6x.md
Migration from Spring Security 5.x

references/troubleshooting.md
Common errors, debugging tips

Constraints and Warnings

Security Constraints

JWT tokens are signed but not encrypted — do not include sensitive data in claims

Always validate exp, iss, and aud claims before trusting the token

Signing keys must be at least 256 bits; never use weak keys in production

Load secrets from environment variables or secure vaults, never from config files

SameSite cookie attribute is essential for CSRF protection in cookie-based flows

Spring Security 6.x Constraints

WebSecurityConfigurerAdapter is removed — use SecurityFilterChain beans only

@EnableGlobalMethodSecurity is deprecated — use @EnableMethodSecurity

Lambda DSL is required for HttpSecurity configuration (no method chaining)

WebSecurityConfigurerAdapter.order() replaced by @Order on @Configuration classes

Token Constraints

Access tokens should expire in 5-15 minutes for security

Refresh tokens should be stored server-side (DB or Redis), never in localStorage

Implement token blacklisting for immediate revocation on logout

jti claim is required for token blacklisting to work correctly

Related Skills

spring-boot-dependency-injection — Constructor injection patterns used throughout

spring-boot-rest-api-standards — REST API security patterns and error handling

unit-test-security-authorization — Testing Spring Security configurations

spring-data-jpa — User entity and repository patterns

spring-boot-actuator — Security monitoring and health endpoints