Jetons JWT et la chaîne de filtres de Spring Security
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...
- il extrait le jeton de l'en-tête
Authorization; - il le confie à un
JwtDecoder, qui vérifie la signature,exp,iss,aud; - un convertisseur transforme le jeton en utilisateur authentifié, avec ses autorités (ses droits) ;
- 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=rolesetspring.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 :
OncePerRequestFiltergarantit 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êteAuthorization. - 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
- Un JWT est signé, pas chiffré : rien de sensible dedans, et jamais un jeton de production dans un outil en ligne.
oauth2ResourceServeravecissuer-uriplutôt qu'un filtre JWT écrit à la main.- Vérifie l'audience avec
spring.security.oauth2.resourceserver.jwt.audiences. - Des jetons d'accès courts, renouvelés avec un jeton de rafraîchissement par le front-end.
- Le jeton dans l'en-tête
Authorization, jamais dans l'adresse ni dans les logs. - Un convertisseur de rôles unique pour le projet, quand les rôles sont dans un claim imbriqué.
logging.level.org.springframework.security=TRACEen local pour comprendre un 401 ou un 403.- Un filtre maison :
OncePerRequestFilter,chaine.doFilter(...), la bonne position, et le nettoyage dans unfinally.
À 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 :
BearerTokenAuthenticationFilterdit qui est-ce,AuthorizationFilterdit s'il a le droit,ExceptionTranslationFilterrépond 401 ou 403. - Des rôles ignorés (403 partout) viennent presque toujours de la conversion des claims en autorités.