Une fois connecté, comment un serveur sait-il que chaque demande ultérieure émane réellement de vous ? Une réponse populaire est un JSON Web Token, ou JWT, généralement prononcé « jot ». Il s’agit d’un petit morceau de données signé que le client envoie à chaque requête, et le serveur peut le vérifier sans toucher à une base de données.

Le moyen le plus rapide de comprendre un JWT est d’en créer un, puis d’essayer de le casser. Nous l’avons fait en utilisant uniquement la bibliothèque standard de Python, sur Python 3.13, et le résultat ci-dessous provient de cette exécution. Ce code est destiné à l’apprentissage. Dans une application réelle, utilisez une bibliothèque bien entretenue, car il est facile de se tromper sur les détails de la vérification.

Qu’est-ce qu’un JWT ?

JWT est un standard ouvert, défini dans la RFC 7519, permettant de transmettre des revendications entre deux parties sous la forme d’une chaîne compacte. Une revendication est simplement une déclaration, telle que « l’ID de cet utilisateur est 42 ». Le token étant signé, le destinataire peut confirmer qui l’a émis et que personne ne l’a modifié.

Pensez à un bracelet de festival. Le personnel à la porte vérifie votre billet une fois et vous donne un bracelet difficile à falsifier. Après cela, chaque stand se contente de regarder le groupe, sans avoir besoin de téléphoner à la billetterie. Un JWT fonctionne à peu près de la même manière pour une API.

Comment fonctionne la connexion JWT

1. L’utilisateur envoie un nom d’utilisateur et un mot de passe au point de terminaison de connexion.
2. Le serveur les vérifie et crée un jeton signé.
3. Le client stocke le jeton.
4. Chaque requête ultérieure l’inclut, généralement dans un en-tête : Authorization: Bearer <token>.
5. Le serveur vérifie la signature et l’expiration, puis lit les réclamations.

Le principal avantage réside dans l’étape 5. Le serveur n’a pas besoin de rechercher une session, ce qui est pratique lorsque de nombreux services ou serveurs doivent vérifier le même jeton. Si vous débutez avec les API, commencez par qu’est-ce qu’une API.

Les trois parties d’un JWT

Un JWT ressemble à du texte aléatoire, mais il s’agit de trois sections codées en Base64URL séparées par des points. En voici un que nous avons généré :

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiI0MiIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNzkzNTAwMDAwLCJleHAiOjE3OTM1MDA5MDB9
.7YfUDH_T-iDh8bMmUT8mmKYwOstzT8Ty--DTTAmQGWM

Nous avons ajouté des sauts de ligne pour faciliter la lecture. Le décodage des deux premières parties donne du JSON simple :

Header:  {"alg":"HS256","typ":"JWT"}
Payload: {"sub":"42","role":"user","iat":1793500000,"exp":1793500900}

Allégations standards

Vous pouvez également ajouter des revendications personnalisées, comme role. Les heures sont des horodatages Unix, en secondes. Gardez la charge utile petite, car le jeton se déplace à chaque demande.

Construisez-en un vous-même

La création d’un jeton implique d’encoder les deux parties JSON, puis de les signer avec un secret à l’aide de HMAC-SHA256 :

import base64, hashlib, hmac, json

SECRET = b"demo-secret-do-not-use-in-production"

def b64url(data):
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()

def sign(message):
    return b64url(hmac.new(SECRET, message.encode(), hashlib.sha256).digest())

def create_token(payload):
    header = {"alg": "HS256", "typ": "JWT"}
    parts = [
        b64url(json.dumps(header, separators=(",", ":")).encode()),
        b64url(json.dumps(payload, separators=(",", ":")).encode()),
    ]
    message = ".".join(parts)
    return message + "." + sign(message)

La vérification fonctionne en recalculant la signature et en la comparant avec celle du jeton. Seule une personne possédant le secret peut en produire un correspondant :

def verify_token(token, now):
    header, payload, signature = token.split(".")
    expected = sign(header + "." + payload)
    if not hmac.compare_digest(signature, expected):
        raise ValueError("bad signature")
    claims = json.loads(b64url_decode(payload))
    if claims["exp"] < now:
        raise ValueError("token expired")
    return claims

Un jeton valide a renvoyé ses réclamations comme prévu. compare_digest est utilisé car il fonctionne en temps constant, ce qui évite les fuites d’informations dues à des différences temporelles.

Essayez de le falsifier

Supposons qu’un attaquant décode la charge utile, modifie "role":"user" en "role":"admin", la code à nouveau et conserve l’ancienne signature. Nous avons essayé ceci, ainsi que deux autres attaques :

Cette dernière tentative vise une véritable faiblesse historique. Certaines bibliothèques faisaient autrefois confiance au propre en-tête du jeton, de sorte qu’un attaquant pouvait simplement déclarer qu’aucune signature n’était nécessaire. Notre code utilise toujours un algorithme fixe, c’est pourquoi il a été rejeté. Dans une vraie bibliothèque, précisez toujours les algorithmes que vous acceptez.

Signé, non crypté

C’est le point le plus mal compris à propos des JWT. Notre faux token a été rejeté, mais son contenu était toujours parfaitement lisible :

{"sub":"42","role":"admin","iat":1793500000,"exp":1793500900}

Base64URL est un codage, pas un cryptage, et n’importe qui peut l’inverser sans aucune clé. La signature empêche les gens de modifier les données, mais pas de les lire. Ne mettez donc jamais de mots de passe, de numéros de carte ou de données personnelles privées dans une charge utile JWT. Si le contenu doit être masqué, utilisez des jetons cryptés (JWE) ou conservez simplement les données sur le serveur.

HS256 contre RS256

Avec la signature asymétrique, d’autres services peuvent vérifier les jetons sans pouvoir créer les leurs, ce qui limite les dégâts en cas de compromission.

JWT vs sessions

Les JWT sont souvent présentés comme un remplacement moderne des sessions. En réalité, chacun a des compromis :

Pour un site Web traditionnel rendu par un serveur, un cookie de session est souvent plus simple et plus sûr. Les JWT ont tendance à avoir plus de sens pour les API consommées par plusieurs services ou pour les clients mobiles.

Où stocker les jetons dans un navigateur

De nombreux guides de sécurité privilégient les cookies HttpOnly, Secure, SameSite pour les applications Web. Quel que soit votre choix, utilisez toujours HTTPS. Pour envoyer un jeton depuis JavaScript, consultez notre Tutoriel API JavaScript Fetch.

Actualiser les jetons

Une expiration courte limite les dégâts d’un jeton volé, mais personne ne veut se connecter toutes les 15 minutes. La solution habituelle utilise deux jetons :

• Jeton d’accès : de courte durée, par exemple quelques minutes, et envoyé avec chaque requête API.
• Jeton d’actualisation : plus durable, stocké plus soigneusement et utilisé uniquement pour obtenir de nouveaux jetons d’accès.

Le serveur garde une trace des jetons d’actualisation afin de pouvoir les révoquer, ce qui vous permet de vous déconnecter de manière pratique. Leur rotation à chaque utilisation vous aide également à détecter le vol, car un ancien token volé est rejoué.

Erreurs de sécurité courantes

• Décoder sans vérifier. La lecture d’une charge utile ne la rend pas fiable. Vérifiez toujours la signature.
• Accepter n’importe quel algorithme. Définissez une liste explicite d’algorithmes autorisés.
• Utilisation d’un secret faible. Les secrets courts peuvent être déchiffrés hors ligne. Utilisez une longue valeur aléatoire et conservez-la hors du contrôle de code source.
• Saut d’expiration. Les jetons sans exp peuvent fonctionner pour toujours s’ils sont volés.
• Ne pas vérifier iss et aud. Sinon, un jeton émis pour un service peut être accepté par un autre.
• Faire confiance aux revendications obsolètes. Un rôle à l’intérieur d’un jeton peut être obsolète jusqu’à son expiration.
• Jetons de journalisation. Toute personne lisant vos journaux peut les réutiliser.
• Ne pas tester les chemins d’échec. Ajoutez des tests pour les jetons expirés et modifiés, ainsi que pour les jetons valides. Notre guide Tests d’API avec Postman peut vous aider.

Pour conclure

Un JWT est constitué de données signées auxquelles un serveur peut faire confiance sans recherche, ni conteneur secret ni mise à niveau automatique au fil des sessions. Utilisez une expiration courte, vérifiez tout avec une bibliothèque maintenue et gardez les données privées hors de la charge utile. Pour le constater par vous-même, exécutez un petit script comme le nôtre, modifiez un caractère d’un jeton et regardez la vérification échouer.

Questions fréquentes

Continuez à apprendre