Vidocq Documentation

Cervantes est en 0.1.0-SNAPSHOT. La spec MicroProfile JWT 2.1 est entièrement couverte (TCK 206 / 206, voir état TCK), mais la SPI publique peut encore évoluer avant la 1.0.0. Cette page documente les correspondances pour préparer une migration progressive.

Côté code applicatif, la migration est triviale : Cervantes consomme strictement les annotations standard org.eclipse.microprofile.jwt. et jakarta.annotation.security.. Aucun import propriétaire à remplacer. Les écarts portent sur la configuration de transport/JWE et sur l’empreinte de dépendances.

Depuis SmallRye JWT

SmallRye JWT est l’implémentation de référence chez Quarkus et chez certains serveurs Jakarta EE. Migration directe — Cervantes vise la stricte conformance à la même spec.

SmallRye JWT Cervantes Note

@RolesAllowed / @PermitAll / @DenyAll

Mêmes annotations

Aucun changement de code applicatif.

@Inject JsonWebToken

Idem

Même interface MP standard.

@Inject @Claim("…") String

Idem, mêmes types supportés

Cervantes ajoute le support de Supplier<T> en plus de ClaimValue<T>, Provider<T>, Instance<T>.

Clés mp.jwt.verify.*

Mêmes clés

publickey, publickey.location, issuer, audiences, publickey.algorithm, clock.skew, token.age, requireiat — identiques.

Clés mp.jwt.token.*

Mêmes clés

header, cookie — identiques. Mode Authorization (défaut) et mode Cookie supportés.

Clés mp.jwt.decrypt.key*

Mêmes clés

RSA-OAEP + A256GCM supportés. A128CBC-HS256 non encore — non couvert par le TCK 2.1.

Dépendances transitives : jose4j, Jackson, …

Aucune (java.security + Champollion)

Empreinte de classpath réduite. Compatibilité jlink immédiate. Compatible GraalVM native-image.

smallrye.jwt.path.sub, …path.groups, …claims.groups

Pas d’équivalent (claims standards uniquement)

Si l’émetteur ne pose pas groups au bon endroit, configurer un filtre côté émetteur ou un OASModelReader côté client. Hors périmètre MP JWT 2.1 standard.

smallrye.jwt.verify.aud (alias)

mp.jwt.verify.audiences (clé standard)

Renommer.

smallrye.jwt.token.header / …cookie

mp.jwt.token.header / mp.jwt.token.cookie

Renommer (préfixe mp.jwt. au lieu de smallrye.jwt.).

Quarkus Dev Mode hot reload

Pas d’équivalent

Le cycle est ./mvnw clean install + redémarrage.

Différences notables

  • A128CBC-HS256 non supporté — Cervantes implémente uniquement A256GCM comme algorithme de chiffrement de contenu JWE (défaut spec, couvert par le TCK). À ajouter si un émetteur l’exige.

  • Pas de réflexion à chaud — l’injection @Claim est résolue par une BCE Vauban à la compilation CDI, pas par un proxy dynamique. Si une convention de typage SmallRye exotique était utilisée (par exemple @Claim List<Integer> sur un champ numérique stocké en string), vérifier que le type concret est dans la liste supportée (voir Référence).

  • Pas de setAccessible(true) — toute classe métier qui doit recevoir une injection @Claim doit être visible CDI normalement (@Dependent, @RequestScoped, …). Si SmallRye ouvrait des packages opens-runtime, Cervantes ne le fait pas — ouvrir explicitement dans module-info.java.

  • mp.jwt.verify.publickey.location — auto-détection PEM vs JWKS basée sur le format du contenu, pas sur l’extension du fichier. Une URL renvoyant un JWK Set valide est traitée comme JWKS, qu’elle se termine par .json, .jwks ou rien.

  • JWKS — refresh paresseux — Cervantes ne fetch pas le JWK Set au démarrage. Le premier kid inconnu déclenche le fetch. Avantage : démarrage rapide et pas de fail-fast si l’émetteur est temporairement down. Inconvénient : la première requête peut être un peu plus lente.

Empreinte de classpath comparée

Choix Lib runtime apportées

SmallRye JWT

smallrye-jwt, jose4j, parsson (ou jackson-databind), microprofile-jwt-auth-api. Indirectement : commons-logging, parfois bouncycastle.

Cervantes

cervantes-core, cervantes-cdi-vauban, cervantes-jaxrs, cervantes-api, cervantes-mp-jwt-api, champollion-impl (JSON-P 2.1, ~120 Ko), ravel-impl (MP Config). Aucune lib crypto/JWT tierce.

Checklist de portage

  1. Remplacer la dépendance SmallRye JWT par cervantes-cdi-vauban + cervantes-jaxrs (ou simplement le wrapper vidocq-runtime-cervantes-jwt-extension si vous packagez via Vidocq Runtime).

  2. Auditer les annotations applicatives : doivent toutes être issues de org.eclipse.microprofile.jwt. et jakarta.annotation.security.. Remplacer toute annotation io.smallrye.jwt.*.

  3. Migrer les propriétés smallrye.jwt. vers leurs équivalents mp.jwt. standard.

  4. Vérifier que les claims attendus existent bien sur les tokens : iss, aud, exp, groups. Pas de remapping path-based exotique.

  5. Lancer les tests unitaires : ./mvnw test.

  6. Lancer le TCK pour valider la conformité : ./run-official-tck-mp-jwt-2.1.sh (voir TCK).

  7. Vérifier en environnement de staging : un token valide passe en 200, un token expiré en 401, un manque de rôle en 403.

  8. Mesurer la latence de validation et comparer (voir Référence vers BENCH.md). Cervantes est ~1.5× plus lent que SmallRye sur le hot-path RS256 — compromis assumé contre la disparition de ~3 Mo de dépendances transitives.

Pour aller plus loin

  • Concepts — modèle JWT, claims, signature, JWK Set.

  • Référence — annotations et clés mp.jwt.*.

  • BUG.md — pièges connus.

  • BENCH.md — comparaison de débit avec SmallRye JWT 4.6.