JWT authentication — stateless auth, signing, refresh token

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyQG9saHViLnZuIiwicm9sZXMiOlsiVVNFUiJdLCJpYXQiOjE3MTM3ODg4MDAsImV4cCI6MTcxMzc5MjQwMH0.QmJC...

{
  "iss": "olhub.org",                  // issuer
  "sub": "[email protected]",              // subject (user identifier)
  "aud": "olhub-api",                  // audience
  "exp": 1713792400,                   // expiration (Unix timestamp)
  "nbf": 1713788800,                   // not before
  "iat": 1713788800,                   // issued at
  "jti": "abc-123-uuid",               // unique JWT ID (for revocation)

  "roles": ["USER", "ADMIN"],          // custom claim
  "tenantId": "acme-corp",             // custom claim
  "name": "Alice"                      // custom claim
}

String secret = "your-256-bit-secret-key-must-be-long-enough";
Algorithm algorithm = Algorithm.HMAC256(secret);

String token = JWT.create()
    .withSubject("[email protected]")
    .withClaim("roles", List.of("USER"))
    .withIssuedAt(new Date())
    .withExpiresAt(new Date(System.currentTimeMillis() + 3600_000))
    .sign(algorithm);

// Validate
JWTVerifier verifier = JWT.require(algorithm).build();
DecodedJWT decoded = verifier.verify(token);

KeyPair keyPair = ...;     // RSA 2048-bit

// Issuer: sign với private key
Algorithm algorithm = Algorithm.RSA256((RSAPublicKey) keyPair.getPublic(), (RSAPrivateKey) keyPair.getPrivate());
String token = JWT.create()...sign(algorithm);

// Validator: verify với public key (chỉ cần public key)
Algorithm verifyAlgo = Algorithm.RSA256((RSAPublicKey) keyPair.getPublic(), null);
JWTVerifier verifier = JWT.require(verifyAlgo).build();
DecodedJWT decoded = verifier.verify(token);

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthConverter()))
            );

        return http.build();
    }
}

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: https://auth.olhub.org/.well-known/jwks.json

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.olhub.org

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          public-key-location: classpath:public.pem

@Bean
public JwtDecoder jwtDecoder() {
    SecretKey key = Keys.hmacShaKeyFor("your-256-bit-secret".getBytes());
    return NimbusJwtDecoder.withSecretKey(key).build();
}

@Bean
public JwtAuthenticationConverter jwtAuthConverter() {
    JwtGrantedAuthoritiesConverter authoritiesConverter = new JwtGrantedAuthoritiesConverter();
    authoritiesConverter.setAuthoritiesClaimName("roles");      // custom claim name
    authoritiesConverter.setAuthorityPrefix("ROLE_");           // prefix matching @hasRole

    JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
    converter.setJwtGrantedAuthoritiesConverter(authoritiesConverter);
    converter.setPrincipalClaimName("sub");
    return converter;
}

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

    private final AuthenticationManager authManager;
    private final JwtIssuer jwtIssuer;

    @PostMapping("/login")
    public TokenResponse login(@Valid @RequestBody LoginRequest req) {
        Authentication auth = authManager.authenticate(
            new UsernamePasswordAuthenticationToken(req.email(), req.password())
        );

        UserDetails user = (UserDetails) auth.getPrincipal();
        String accessToken = jwtIssuer.issueAccessToken(user);
        String refreshToken = jwtIssuer.issueRefreshToken(user);

        return new TokenResponse(accessToken, refreshToken, "Bearer", 3600L);
    }
}

public record LoginRequest(@NotBlank @Email String email, @NotBlank String password) {}
public record TokenResponse(String accessToken, String refreshToken, String tokenType, Long expiresIn) {}

@Service
@RequiredArgsConstructor
public class JwtIssuer {

    private final JwtEncoder encoder;          // Spring Security 5.7+ JwtEncoder

    public String issueAccessToken(UserDetails user) {
        Instant now = Instant.now();
        List<String> roles = user.getAuthorities().stream()
            .map(GrantedAuthority::getAuthority)
            .map(a -> a.replaceFirst("^ROLE_", ""))
            .toList();

        JwtClaimsSet claims = JwtClaimsSet.builder()
            .issuer("olhub.org")
            .subject(user.getUsername())
            .audience(List.of("olhub-api"))
            .issuedAt(now)
            .expiresAt(now.plus(Duration.ofHours(1)))
            .id(UUID.randomUUID().toString())
            .claim("roles", roles)
            .build();

        return encoder.encode(JwtEncoderParameters.from(claims)).getTokenValue();
    }

    public String issueRefreshToken(UserDetails user) {
        Instant now = Instant.now();
        JwtClaimsSet claims = JwtClaimsSet.builder()
            .issuer("olhub.org")
            .subject(user.getUsername())
            .issuedAt(now)
            .expiresAt(now.plus(Duration.ofDays(30)))
            .id(UUID.randomUUID().toString())
            .claim("type", "refresh")
            .build();

        return encoder.encode(JwtEncoderParameters.from(claims)).getTokenValue();
    }
}

@Configuration
public class JwtConfig {

    @Value("${app.jwt.secret}")
    private String secret;

    @Bean
    public JwtEncoder jwtEncoder() {
        SecretKey key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
        JWKSource<SecurityContext> jwkSource = (jwkSelector, context) ->
            jwkSelector.select(new JWKSet(new OctetSequenceKey.Builder(key).build()));
        return new NimbusJwtEncoder(jwkSource);
    }

    @Bean
    public JwtDecoder jwtDecoder() {
        SecretKey key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
        return NimbusJwtDecoder.withSecretKey(key).macAlgorithm(MacAlgorithm.HS256).build();
    }
}

@PostMapping("/refresh")
public TokenResponse refresh(@Valid @RequestBody RefreshRequest req) {
    Jwt jwt = refreshTokenDecoder.decode(req.refreshToken());

    if (!"refresh".equals(jwt.getClaim("type"))) {
        throw new InvalidTokenException("Not a refresh token");
    }

    String username = jwt.getSubject();
    UserDetails user = userDetailsService.loadUserByUsername(username);

    String newAccessToken = jwtIssuer.issueAccessToken(user);
    String newRefreshToken = jwtIssuer.issueRefreshToken(user);

    // Optionally: revoke old refresh token (sliding expiration)
    refreshTokenStore.revoke(jwt.getId());

    return new TokenResponse(newAccessToken, newRefreshToken, "Bearer", 3600L);
}

@Service
public class TokenDenylistService {

    private final RedisTemplate<String, String> redis;

    public void revoke(String jti, Duration remainingTtl) {
        redis.opsForValue().set("revoked:" + jti, "true", remainingTtl);
    }

    public boolean isRevoked(String jti) {
        return Boolean.TRUE.equals(redis.hasKey("revoked:" + jti));
    }
}

@Component
public class JwtRevocationFilter extends OncePerRequestFilter {

    private final TokenDenylistService denylist;

    protected void doFilterInternal(...) {
        String token = extractToken(request);
        if (token != null) {
            Jwt jwt = jwtDecoder.decode(token);
            if (denylist.isRevoked(jwt.getId())) {
                response.setStatus(401);
                return;
            }
        }
        chain.doFilter(req, res);
    }
}

@Entity
public class RefreshToken {
    @Id String id;          // JTI
    String username;
    Instant issuedAt;
    Instant expiresAt;
    boolean revoked;
}

// On refresh:
// 1. Verify refresh token in DB, not revoked
// 2. Mark old refresh token revoked
// 3. Issue new access + new refresh
// 4. Save new refresh to DB

// On logout:
// 1. Mark current refresh token revoked
// 2. Access token expire naturally (5-15 min)

// Header: {"alg":"none","typ":"JWT"}
// Payload: {"sub":"admin","roles":["ADMIN"]}
// Signature: empty

@Bean
public JwtDecoder jwtDecoder() {
    return NimbusJwtDecoder
        .withSecretKey(key)
        .macAlgorithm(MacAlgorithm.HS256)         // explicit allow
        .build();
    // Reject "none" automatically
}

// SAI
String secret = "my-secret-key";

// DUNG
@Value("${app.jwt.secret}")
String secret;

openssl rand -base64 32
# G3wKf9XzN2pQ8vL6tH4mR1yE5sD7uA0bC9wY3jK7iN8=

curl https://api.olhub.org/orders?token=eyJ...     # SAI — leak via log

{
  "sub": "[email protected]",
  "ssn": "123-45-6789",          // SAI — payload base64, anyone decode
  "creditCard": "4111111111111111"
}

public record AppUserPrincipal(String email, List<String> roles, String tenantId) {}

@Bean
public JwtAuthenticationConverter jwtAuthConverter() {
    JwtAuthenticationConverter converter = new JwtAuthenticationConverter();

    converter.setJwtGrantedAuthoritiesConverter(jwt -> {
        List<String> roles = jwt.getClaimAsStringList("roles");
        return roles.stream()
            .map(r -> new SimpleGrantedAuthority("ROLE_" + r))
            .collect(Collectors.toList());
    });

    return converter;
}

// Custom resolver to convert Jwt → AppUserPrincipal
@Component
public class AppUserPrincipalResolver implements HandlerMethodArgumentResolver {

    public boolean supportsParameter(MethodParameter param) {
        return param.hasParameterAnnotation(CurrentUser.class)
            && param.getParameterType().equals(AppUserPrincipal.class);
    }

    public Object resolveArgument(MethodParameter param, ...) {
        Jwt jwt = (Jwt) SecurityContextHolder.getContext()
            .getAuthentication()
            .getPrincipal();

        return new AppUserPrincipal(
            jwt.getSubject(),
            jwt.getClaimAsStringList("roles"),
            jwt.getClaimAsString("tenantId")
        );
    }
}

// Use trong controller
@GetMapping("/me")
public AppUserPrincipal me(@CurrentUser AppUserPrincipal user) {
    return user;
}

// Login
POST /api/auth/login
Body: { email, password }
Response: { accessToken, refreshToken, expiresIn }

// Use API
GET /api/projects
Authorization: Bearer eyJ...

// Refresh
POST /api/auth/refresh
Body: { refreshToken }
Response: { accessToken, refreshToken (new), expiresIn }

// Logout
POST /api/auth/logout
Authorization: Bearer eyJ...
Response: 204 No Content (revoke refresh token in DB)