Jetons JWT et la chaîne de filtres de Spring Security

Publié le · Mis à jour le

L'idée en une phrase

Un JWT est un jeton signé que le client envoie à chaque requête pour prouver qui il est. Côté serveur, la chaîne de filtres de Spring Security le lit, vérifie sa signature et sa validité, en déduit l'utilisateur et ses droits, puis décide si la requête peut atteindre le contrôleur. Cette fiche ouvre la boîte : ce que contient un jeton, comment il est vérifié, et ce que fait chaque filtre.

Note : cette fiche approfondit la fiche sur Spring Security (authentification, autorisation, règles d'accès). Lis-la d'abord si ce n'est pas déjà fait.

Une image pour comprendre : le bracelet de festival

À l'entrée d'un festival, on vérifie ton billet une seule fois, à la billetterie. On te pose alors un bracelet :

  • il indique tes droits : les jours, l'accès à l'espace VIP ;
  • il porte un hologramme impossible à imiter : personne ne peut fabriquer ou modifier un bracelet ;
  • il a une date de fin : après dimanche, il ne sert plus à rien.

Ensuite, devant chaque scène, un agent regarde le bracelet. Il ne téléphone pas à la billetterie : l'hologramme et les informations du bracelet lui suffisent.

Mais le bracelet a aussi ses limites :

  • tout le monde peut lire ce qui est écrit dessus : ce n'est pas un endroit pour un secret ;
  • si quelqu'un te le prend, il peut l'utiliser à ta place jusqu'à sa date de fin.

Un JWT, c'est exactement ce bracelet :

Festival JWT
la billetterie le fournisseur d'identité (Keycloak, Entra ID…), qui vérifie le mot de passe
le bracelet le jeton, envoyé à chaque requête
les droits écrits dessus les informations du jeton (claims) : identifiant, rôles
l'hologramme la signature
la date de fin l'expiration (exp)
les agents devant les scènes la chaîne de filtres de ton API

À quoi ressemble un JWT

Un JWT est une longue chaîne en trois parties, séparées par des points :

eyJhbGciOiJSUzI1NiIsImtpZCI6ImNsZS0yMDI2In0.eyJzdWIiOiI4ZjNhLi4uIiwiZXhwIjoxNzk0MDAwMDAwfQ.k7Hq2…
└──────────── en-tête ────────────────────┘ └───────────── contenu ──────────────────────┘ └ signature ┘

Les deux premières parties sont simplement du JSON encodé (en Base64URL). N'importe qui peut les décoder :

L'en-tête dit comment le jeton est signé :

{
  "alg": "RS256",
  "kid": "cle-2026"
}

Le contenu (payload) contient les informations, appelées claims :

{
  "iss": "https://identite.exemple.fr/realms/boutique",
  "sub": "8f3a2c1e-7b4d-4e9a-9c2f-1a2b3c4d5e6f",
  "aud": "api-boutique",
  "iat": 1793996400,
  "exp": 1794000000,
  "email": "alice@exemple.fr",
  "realm_access": { "roles": ["CLIENT"] }
}
Claim Signification
iss (issuer) qui a émis le jeton : l'adresse du fournisseur d'identité
sub (subject) l'identifiant unique de l'utilisateur
aud (audience) à qui est destiné le jeton : quelle API a le droit de l'accepter
iat (issued at) la date d'émission
exp (expiration) la date à partir de laquelle le jeton n'est plus valable
les autres ce que le fournisseur d'identité y ajoute : e-mail, rôles…

Les dates sont en secondes depuis le 1er janvier 1970 (le format « timestamp Unix »).

La signature est calculée à partir des deux premières parties, avec une clé secrète que seul le fournisseur d'identité possède. Si quelqu'un modifie une seule lettre du contenu (pour se donner le rôle ADMIN, par exemple), la signature ne correspond plus, et le jeton est refusé.

Signé, mais pas chiffré

C'est le point à retenir : un JWT est signé, ce qui empêche de le modifier. Il n'est pas chiffré : tout le monde peut le lire.

  • ❌ jamais de donnée sensible dans un jeton : mot de passe, numéro de carte, information médicale ;
  • ✅ un identifiant, un e-mail, des rôles : ce que le client a de toute façon le droit de savoir.

Astuce : pour lire le contenu d'un jeton pendant le développement, il suffit de décoder ses deux premières parties : de nombreux outils le font (y compris en ligne). Mais ne colle jamais un jeton de production dans un site web : tant qu'il n'a pas expiré, c'est une clé d'accès à ton compte.

Comment la signature est vérifiée

Il existe deux grandes familles de signatures :

Famille Exemple Principe
asymétrique RS256, ES256 le fournisseur signe avec une clé privée qu'il garde secrète ; tout le monde vérifie avec la clé publique correspondante
symétrique HS256 la même clé secrète sert à signer et à vérifier : chaque API qui vérifie doit la connaître

Avec un fournisseur d'identité, c'est presque toujours asymétrique. Ton API n'a besoin d'aucun secret : elle télécharge les clés publiques du fournisseur, publiées à une adresse standard (le JWKS, JSON Web Key Set). Le champ kid de l'en-tête indique quelle clé a servi.

C'est ce que fait Spring avec une seule ligne de configuration :

spring.security.oauth2.resourceserver.jwt.issuer-uri=https://identite.exemple.fr/realms/boutique

Au démarrage, Spring interroge cette adresse, découvre où sont publiées les clés, et les utilise pour vérifier chaque jeton.

Ce qui est vérifié pour chaque jeton

Vérification Si elle échoue
la signature correspond jeton falsifié ou abîmé → 401
exp : le jeton n'a pas expiré jeton périmé → 401
iss : il vient bien du bon fournisseur jeton émis ailleurs → 401
aud : il est bien destiné à cette API (si configuré) jeton prévu pour une autre application → 401

La vérification de l'audience mérite d'être activée : sans elle, un jeton émis pour une autre application du même fournisseur serait accepté par la tienne.

spring.security.oauth2.resourceserver.jwt.audiences=api-boutique

Note : Spring tolère par défaut un petit décalage d'horloge (environ une minute) entre ton serveur et le fournisseur d'identité, pour qu'un jeton ne soit pas refusé à quelques secondes près.

La durée de vie d'un jeton

Le serveur ne garde aucune trace des jetons qu'il accepte : il vérifie seulement la signature et les dates. C'est ce qui le rend simple et rapide (on dit sans état, stateless). Mais c'est aussi sa limite : un jeton volé reste valable jusqu'à son expiration, comme le bracelet de festival.

D'où l'organisation habituelle :

Jeton Durée de vie Rôle
jeton d'accès (access token) courte : quelques minutes envoyé à l'API à chaque requête
jeton de rafraîchissement (refresh token) plus longue sert uniquement à demander un nouveau jeton d'accès au fournisseur d'identité

Le front-end renouvelle le jeton d'accès régulièrement, sans que l'utilisateur ait à se reconnecter. Ton API, elle, ne voit que les jetons d'accès.

La chaîne de filtres en détail

Où elle se trouve

Spring Security s'installe dans le serveur web comme un filtre placé devant toute l'application. Ce filtre contient lui-même une liste de filtres de sécurité : la SecurityFilterChain que tu configures. Chaque requête les traverse dans l'ordre.

Voici les principaux, dans l'ordre où une requête les rencontre (la liste réelle est un peu plus longue) :

requête HTTP
   │
   ├─ SecurityContextHolderFilter       prépare le contexte de sécurité de la requête
   ├─ HeaderWriterFilter                ajoute des en-têtes de sécurité à la réponse
   ├─ CorsFilter                        applique les règles CORS
   ├─ CsrfFilter                        vérifie le jeton CSRF (si activé)
   ├─ LogoutFilter                      gère la déconnexion
   ├─ BearerTokenAuthenticationFilter   lit et vérifie le JWT            ← l'authentification
   ├─ AnonymousAuthenticationFilter     pas de jeton ? marque la requête comme « anonyme »
   ├─ ExceptionTranslationFilter        transforme les refus en 401 ou 403
   ├─ AuthorizationFilter               applique les règles d'accès     ← l'autorisation
   ▼
DispatcherServlet → ton contrôleur

Deux étapes font l'essentiel du travail : qui est-ce ? (BearerTokenAuthenticationFilter) puis a-t-il le droit ? (AuthorizationFilter).

BearerTokenAuthenticationFilter : qui est-ce ?

Pour une requête avec un jeton :

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
  1. il extrait le jeton de l'en-tête Authorization ;
  2. il le confie à un JwtDecoder, qui vérifie la signature, exp, iss, aud ;
  3. un convertisseur transforme le jeton en utilisateur authentifié, avec ses autorités (ses droits) ;
  4. le résultat est rangé dans le contexte de sécurité de la requête.

Si le jeton est invalide (signature fausse, expiré), la requête s'arrête là : 401.

Si la requête n'a pas de jeton du tout, ce filtre ne fait rien : la requête continue, en tant qu'utilisateur anonyme. C'est le filtre d'autorisation, plus loin, qui décidera si une personne anonyme a le droit d'appeler cette adresse (permitAll) ou non.

AuthorizationFilter : a-t-il le droit ?

Il compare l'utilisateur du contexte de sécurité avec les règles de authorizeHttpRequests (voir la fiche sur Spring Security) : permitAll, authenticated, hasRole…

ExceptionTranslationFilter : 401 ou 403 ?

Quand le filtre d'autorisation refuse l'accès, ExceptionTranslationFilter choisit la réponse :

Situation Réponse
l'utilisateur est anonyme (aucun jeton) 401, avec un en-tête WWW-Authenticate: Bearer
l'utilisateur est authentifié, mais n'a pas le bon droit 403

Ces réponses sont produites avant le contrôleur : ton @RestControllerAdvice ne les voit pas. Pour changer leur format (renvoyer un ProblemDetail, par exemple), on configure un AuthenticationEntryPoint (pour le 401) et un AccessDeniedHandler (pour le 403) dans la chaîne de filtres.

Voir la chaîne en action

Quand une requête est refusée sans que tu comprennes pourquoi, active les logs de Spring Security, en local :

logging.level.org.springframework.security=TRACE

Au démarrage, la liste complète des filtres s'affiche. Puis, pour chaque requête, tu vois chaque filtre traversé, le jeton analysé, les autorités trouvées, et la règle qui a accepté ou refusé l'accès. C'est le moyen le plus rapide de comprendre un 401 ou un 403 inattendu.

Des rôles du jeton aux autorités Spring

Par défaut, Spring transforme le claim scope (ou scp) du jeton en autorités préfixées par SCOPE_ : un jeton avec "scope": "commandes.lire" donne l'autorité SCOPE_commandes.lire.

Mais beaucoup de fournisseurs rangent les rôles ailleurs. Keycloak, par exemple, les met dans realm_access.roles. Spring ne les voit pas, et hasRole("ADMIN") refuse tout : 403 pour tout le monde, administrateurs compris.

Il faut alors indiquer à Spring où trouver les rôles, avec un convertisseur :

@Bean
JwtAuthenticationConverter convertisseurJwt() {
    JwtAuthenticationConverter convertisseur = new JwtAuthenticationConverter();
    convertisseur.setJwtGrantedAuthoritiesConverter(jeton -> {
        Map<String, Object> realmAccess = jeton.getClaimAsMap("realm_access");
        if (realmAccess == null) {
            return List.of();
        }
        @SuppressWarnings("unchecked")
        List<String> roles = (List<String>) realmAccess.getOrDefault("roles", List.of());
        return roles.stream()
                .map(role -> (GrantedAuthority) new SimpleGrantedAuthority("ROLE_" + role))
                .toList();
    });
    return convertisseur;
}

Spring utilise automatiquement ce bean. Le rôle ADMIN du jeton devient l'autorité ROLE_ADMIN, que hasRole("ADMIN") reconnaît.

Note : quand les rôles sont dans un claim de premier niveau ("roles": ["ADMIN"]), deux propriétés suffisent, sans code : spring.security.oauth2.resourceserver.jwt.authorities-claim-name=roles et spring.security.oauth2.resourceserver.jwt.authority-prefix=ROLE_. Le convertisseur n'est utile que pour un claim imbriqué, comme celui de Keycloak.

Ce convertisseur s'écrit une fois pour tout le projet. S'il existe déjà, c'est là qu'il faut regarder quand les rôles semblent ignorés.

Ajouter son propre filtre

On peut insérer un filtre dans la chaîne, par exemple pour ajouter à chaque ligne de log l'identifiant de l'utilisateur et un identifiant de requête :

public class ContexteLogFiltre extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest requete, HttpServletResponse reponse,
                                    FilterChain chaine) throws ServletException, IOException {
        MDC.put("requeteId", UUID.randomUUID().toString());
        try {
            chaine.doFilter(requete, reponse); // ✅ passe la main au filtre suivant
        } finally {
            MDC.clear(); // ✅ toujours nettoyer : le thread servira à une autre requête
        }
    }
}
http.addFilterAfter(new ContexteLogFiltre(), BearerTokenAuthenticationFilter.class);

Trois points importants :

  • OncePerRequestFilter garantit que le filtre ne s'exécute qu'une fois par requête ;
  • chaine.doFilter(...) passe la requête au filtre suivant : l'oublier bloque la requête, qui ne reçoit jamais de réponse ;
  • la position compte : placé après BearerTokenAuthenticationFilter, le filtre peut lire l'utilisateur authentifié dans le contexte de sécurité ; placé avant, il ne le connaît pas encore.

N'écris pas ton propre filtre JWT

Beaucoup de tutoriels montrent un JwtAuthenticationFilter écrit à la main, qui découpe l'en-tête, décode le jeton avec une bibliothèque, et remplit le contexte de sécurité lui-même. Avec Spring Boot, c'est inutile : oauth2ResourceServer(...) fait tout cela, en vérifiant correctement la signature, les dates, l'émetteur et l'audience.

Un filtre maison oublie facilement une de ces vérifications, et chaque oubli est une faille. Si ton projet en contient un, il a peut-être une bonne raison historique : renseigne-toi avant d'y toucher, et ne le recopie pas dans un nouveau projet.

Plusieurs chaînes de filtres

Une application peut avoir plusieurs SecurityFilterChain, chacune pour une partie des adresses. Par exemple, une chaîne pour l'API (avec JWT) et une autre pour les adresses de supervision (/actuator/**) :

@Bean
@Order(1)
SecurityFilterChain supervision(HttpSecurity http) throws Exception {
    http.securityMatcher("/actuator/**") // cette chaîne ne s'applique qu'à ces adresses
        .authorizeHttpRequests(acces -> acces
            .requestMatchers("/actuator/health").permitAll()
            .anyRequest().hasRole("SUPERVISION"));
    return http.build();
}

@Bean
@Order(2)
SecurityFilterChain api(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(acces -> acces.anyRequest().authenticated())
        .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
    return http.build();
}

Pour chaque requête, Spring prend la première chaîne (selon @Order) dont le securityMatcher correspond, et uniquement celle-là. Les règles d'une chaîne ne s'appliquent jamais aux adresses d'une autre.

Les pièges

  • Un jeton dans l'adresse (?token=eyJ…) : les adresses sont enregistrées dans les logs des serveurs, l'historique du navigateur, les outils de supervision. Le jeton y reste lisible. Toujours dans l'en-tête Authorization.
  • Un jeton dans les logs : jamais, même au niveau DEBUG. Tant qu'il n'a pas expiré, c'est une clé d'accès.
  • Des données sensibles dans le jeton : il est lisible par tous.
  • Faire confiance au contenu sans vérification : décoder un jeton pour lire son contenu n'est pas le vérifier. Seul le JwtDecoder, avec la signature, garantit qu'il est authentique.
  • Des jetons d'accès qui durent des jours : un jeton volé serait utilisable tout ce temps.
  • Oublier l'audience : un jeton prévu pour une autre application du même fournisseur serait accepté.

Les bonnes habitudes

  1. Un JWT est signé, pas chiffré : rien de sensible dedans, et jamais un jeton de production dans un outil en ligne.
  2. oauth2ResourceServer avec issuer-uri plutôt qu'un filtre JWT écrit à la main.
  3. Vérifie l'audience avec spring.security.oauth2.resourceserver.jwt.audiences.
  4. Des jetons d'accès courts, renouvelés avec un jeton de rafraîchissement par le front-end.
  5. Le jeton dans l'en-tête Authorization, jamais dans l'adresse ni dans les logs.
  6. Un convertisseur de rôles unique pour le projet, quand les rôles sont dans un claim imbriqué.
  7. logging.level.org.springframework.security=TRACE en local pour comprendre un 401 ou un 403.
  8. Un filtre maison : OncePerRequestFilter, chaine.doFilter(...), la bonne position, et le nettoyage dans un finally.

À retenir

  • Un JWT a trois parties : en-tête, contenu (les claims) et signature. Les deux premières sont lisibles par tous.
  • La signature empêche toute modification ; ton API la vérifie avec les clés publiques du fournisseur d'identité, sans aucun secret.
  • Pour chaque jeton, Spring vérifie la signature, l'expiration, l'émetteur et, si configurée, l'audience.
  • Un jeton volé reste valable jusqu'à son expiration : les jetons d'accès doivent être courts.
  • La chaîne de filtres traite chaque requête dans l'ordre : BearerTokenAuthenticationFilter dit qui est-ce, AuthorizationFilter dit s'il a le droit, ExceptionTranslationFilter répond 401 ou 403.
  • Des rôles ignorés (403 partout) viennent presque toujours de la conversion des claims en autorités.

Avis sur l'article

Pas encore de note : soyez le premier à donner votre avis.

Les avis sont publiés après validation par le modérateur.

Votre note