La plupart des implémentations JWT sous Spring Security "marchent" en démo puis s'effondrent en production : les rôles ne matchent jamais, le logout ne révoque rien, et une requête sur deux renvoie 403 au lieu de 401. Le problème n'est presque jamais la cryptographie du token, mais la mécompréhension de la chaîne de filtres Spring Security dans laquelle ce token doit s'insérer.

Le piège du tutoriel qui "marche"

Le pattern classique copié depuis un tutoriel : un filtre unique qui lit l'en-tête Authorization, décode le JWT, et pousse un Authentication dans le SecurityContextHolder. Ça fonctionne pour la route de login et une route protégée testée à la main. Puis arrivent les vrais problèmes : les exceptions d'authentification remontent comme des 500, les rôles définis côté métier ("ADMIN") ne correspondent jamais aux hasRole("ADMIN") de Spring (qui attend un préfixe ROLE_), et personne ne sait comment invalider un token avant son expiration.

Ces symptômes ne sont pas des bugs isolés. Ils viennent tous du même point : Spring Security n'est pas "un filtre qui vérifie un token", c'est une chaîne ordonnée de filtres avec un contrat précis sur qui lève quelle exception, à quel moment, et comment elle est traduite en réponse HTTP.

Comment fonctionne réellement la chaîne de filtres

Depuis Spring Security 5.7 (et obligatoire en 6.x), WebSecurityConfigurerAdapter est supprimé au profit d'un bean SecurityFilterChain explicite. Pour une API stateless, trois décisions structurent tout le reste : désactiver la gestion de session, positionner le filtre JWT avant UsernamePasswordAuthenticationFilter, et définir un AuthenticationEntryPoint qui renvoie bien du JSON et un 401 plutôt que la redirection par défaut vers une page de login.

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
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 {
        return http
            .csrf(AbstractHttpConfigurer::disable)
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint((req, res, e) -> {
                    res.setContentType("application/json");
                    res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
                    res.getWriter().write("{\"error\":\"unauthorized\"}");
                })
            )
            .authenticationProvider(authenticationProvider)
            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class)
            .build();
    }
}

Désactiver CSRF ici n'est pas un raccourci dangereux : la protection CSRF protège contre l'usage abusif d'un cookie de session envoyé automatiquement par le navigateur. Sans session ni cookie, il n'y a pas de surface CSRF à protéger (à condition que le token ne soit pas lui-même stocké dans un cookie non-SameSite, voir plus bas).

Générer et valider le token correctement

Le choix de l'algorithme compte. HS256 (symétrique) est simple mais oblige à partager le secret avec tout service qui doit valider le token ; RS256 (asymétrique) permet à un service de vérifier le token avec une clé publique sans jamais détenir la clé privée qui l'a signé, ce qui est préférable dès qu'on a plusieurs microservices.

@Component
public class JwtService {

    private final SecretKey signingKey;
    private static final long ACCESS_TOKEN_TTL_MS = 15 * 60 * 1000; // 15 minutes

    public JwtService(@Value("${jwt.secret}") String secret) {
        this.signingKey = Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));
    }

    public String generateAccessToken(UserDetails user) {
        Instant now = Instant.now();
        return Jwts.builder()
            .subject(user.getUsername())
            .claim("roles", user.getAuthorities().stream()
                .map(GrantedAuthority::getAuthority).toList())
            .issuedAt(Date.from(now))
            .expiration(Date.from(now.plusMillis(ACCESS_TOKEN_TTL_MS)))
            .signWith(signingKey)
            .compact();
    }

    public Claims validate(String token) {
        return Jwts.parser()
            .verifyWith(signingKey)
            .build()
            .parseSignedClaims(token)
            .getPayload();
    }
}

Un détail qui revient souvent en revue de code : les rôles stockés dans le claim doivent déjà porter le préfixe ROLE_ si on compte utiliser hasRole(), ou alors il faut utiliser hasAuthority() avec le nom brut. Mélanger les deux conventions est la cause numéro un des 403 inexpliqués sur des endpoints pourtant correctement protégés.

Le filtre d'authentification JWT

Le filtre ne doit faire qu'une chose : extraire le token, le valider, construire un Authentication et le poser dans le contexte. Il ne doit jamais lui-même décider d'un 401/403 ; cette responsabilité appartient à la configuration d'exception handling vue plus haut.

@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 {
        String header = request.getHeader("Authorization");
        if (header == null || !header.startsWith("Bearer ")) {
            filterChain.doFilter(request, response);
            return;
        }

        String token = header.substring(7);
        try {
            Claims claims = jwtService.validate(token);
            UserDetails user = userDetailsService.loadUserByUsername(claims.getSubject());
            var auth = new UsernamePasswordAuthenticationToken(
                user, null, user.getAuthorities());
            auth.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
            SecurityContextHolder.getContext().setAuthentication(auth);
        } catch (JwtException | IllegalArgumentException ex) {
            SecurityContextHolder.clearContext();
        }

        filterChain.doFilter(request, response);
    }
}

Laisser passer la requête même en cas d'échec de validation (plutôt que de bloquer dans le filtre) est volontaire : c'est authorizeHttpRequests plus bas dans la chaîne qui décidera si la route exige une authentification, et exceptionHandling qui produira la bonne réponse.

Diagnostiquer les problèmes typiques

Trois symptômes reviennent systématiquement en revue :

  • 401 attendu, 403 reçu : quasiment toujours un problème d'ordre des filtres, ou un authorizeHttpRequests qui matche la route avant que le filtre JWT n'ait eu la chance de peupler le contexte.
  • "Access denied" sur un rôle qui semble correct : vérifier le préfixe ROLE_ et la casse exacte du claim face à l'expression hasRole/hasAuthority.
  • Le token expire pendant une suite de requêtes concurrentes : un refresh token mal géré côté client déclenche plusieurs appels de refresh en parallèle, dont un seul doit réussir ; sans verrou côté client (ou rotation idempotente côté serveur), on obtient des race conditions qui déconnectent l'utilisateur de façon aléatoire.

Où stocker le token côté client

Le choix du stockage côté navigateur détermine quelle famille d'attaque on accepte. Un token dans localStorage est accessible à n'importe quel script exécuté sur la page, donc vulnérable à toute faille XSS, même mineure, qui permettrait d'exfiltrer le token vers un domaine tiers. Un cookie httpOnly n'est pas lisible par JavaScript, ce qui neutralise ce vecteur, mais réintroduit une surface CSRF puisque le navigateur l'attache automatiquement à chaque requête vers le domaine.

@PostMapping("/api/auth/login")
public ResponseEntity<Void> login(@RequestBody LoginRequest req, HttpServletResponse response) {
    String token = authenticate(req);
    ResponseCookie cookie = ResponseCookie.from("access_token", token)
        .httpOnly(true)
        .secure(true)
        .sameSite("Strict")
        .path("/api")
        .maxAge(Duration.ofMinutes(15))
        .build();
    response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
    return ResponseEntity.ok().build();
}

Avec SameSite=Strict (ou Lax selon le besoin de navigation inter-sites), le cookie n'est de toute façon pas envoyé lors d'une requête initiée depuis un autre domaine, ce qui couvre l'essentiel du risque CSRF sans réactiver la protection CSRF classique de Spring. Le compromis correct dépend du profil de risque : une API consommée uniquement par un frontend que l'on maîtrise tolère bien le cookie httpOnly ; une API publique consommée par des clients tiers variés (mobile, scripts serveur à serveur) s'accommode mieux d'un header Authorization classique, où le risque XSS n'a de sens que si le client est lui-même une page web.

Le vrai problème : la révocation

Un JWT stateless signé ne peut pas être invalidé avant son expiration sans un minimum d'état côté serveur. Trois approches réalistes :

  1. TTL court sans révocation : access token de 10-15 minutes, acceptable si la fenêtre de risque résiduelle après un logout est tolérable pour le métier.
  2. Refresh token en base avec rotation : chaque refresh génère un nouveau refresh token et invalide l'ancien ; si un refresh token déjà utilisé est présenté à nouveau, c'est le signal d'un vol, et on révoque toute la famille de tokens de cet utilisateur.
  3. Liste de révocation (jti) dans Redis : coût d'un lookup cache à chaque requête, mais permet un logout immédiat et un "déconnecter tous les appareils" réel.

Quand la solution simple ne suffit pas

Si le produit a une exigence explicite de type "l'admin doit pouvoir forcer la déconnexion immédiate d'un utilisateur", aucune des variantes purement stateless ne la satisfait : il faut un lookup serveur, donc un peu d'état partagé. Ce n'est pas un échec de l'architecture JWT, c'est un compromis assumé entre scalabilité stateless et contrôle fin de session. Un lookup Redis en O(1) par requête reste largement moins coûteux qu'une session complète chargée depuis une base relationnelle, donc le compromis reste rentable dans l'immense majorité des cas.

Une authentification JWT correcte n'est pas une histoire de bibliothèque de signature, c'est une histoire de chaîne de filtres bien ordonnée et de décision explicite sur ce qui est et n'est pas révocable. Traiter la révocation comme un détail à régler plus tard produit systématiquement une fonctionnalité de logout qui ne logout rien.