jwt-auth

JWT Auth — Scaffold

Bearer-token auth for a stateless API. The cardinal rule: never read claims from a token you have not verified. Prefer the framework path; the custom filter is a fallback, not the default.

Step 1 — Detect conventions

• Confirm a SecurityFilterChain exists (use the security-filter-chain skill first); JWT auth plugs into it with SessionCreationPolicy.STATELESS and CSRF disabled.
• Check for an issuer/JWKS endpoint (Auth0/Keycloak/Cognito) → strongly favors Option 1.
• Confirm the signing secret/JWKS URI is in config/env, never in source.

Step 2 — Option 1 (RECOMMENDED): Spring Security resource server

Let Spring validate the token — signature, exp, nbf, issuer — no hand-rolled crypto:

// build.gradle: implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'
http.oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));

@Bean // JWKS (asymmetric) — the usual case with an external IdP:
JwtDecoder jwtDecoder(@Value("${security.jwt.jwks-uri}") String jwksUri) {
    return NimbusJwtDecoder.withJwkSetUri(jwksUri).build();
}
// HMAC (shared secret) variant:
//   NimbusJwtDecoder.withSecretKey(new SecretKeySpec(secret.getBytes(UTF_8), "HmacSHA256"))
//       .macAlgorithm(MacAlgorithm.HS256).build();

Map scopes/roles with a JwtAuthenticationConverter if needed. Choose this whenever an IdP issues the tokens — you maintain zero verification code.

Step 3 — Option 2 (only if you must): custom filter

For teams that issue their own tokens and can't add the resource server. Render from assets/, substitute {{PACKAGE}}:

• JwtService.java.tmpl → <pkg>/security/JwtService.java (issue + verify via jjwt)
• JwtAuthenticationFilter.java.tmpl → <pkg>/security/JwtAuthenticationFilter.java
• JwtAuthenticationEntryPoint.java.tmpl → <pkg>/security/JwtAuthenticationEntryPoint.java

Requires jjwt: io.jsonwebtoken:jjwt-api + runtime jjwt-impl, jjwt-jackson.

What the templates guarantee:

• Jwts.parser().verifyWith(key).build().parseSignedClaims(token) — verifies the signature, rejects alg=none and algorithm-confusion, and enforces exp/nbf.
• The filter only trusts a token after verify returns; on any JwtException it clears the context and returns 401 JSON via the entry point — never partially authenticated.
• The secret is injected from ${security.jwt.secret} (env), HS256 key >= 256 bits.
• Authorities are mapped from a roles claim (fallback ROLE_USER) in the filter's authorities(...) helper — adjust the claim name/prefix to match your issuer so hasRole(...) / @PreAuthorize reflect real token roles.