Comment fonctionne JWT : Guide complet des JSON Web Tokens

JSON Web Tokens (JWT) are the most widely used standard for stateless authentication in modern web applications. This guide explains how JWT works, its structure, security best practices, and common pitfalls.

What is JWT?

A JWT is a compact, URL-safe token that carries claims (data) between two parties. It consists of three parts separated by dots: Header.Payload.Signature. The token is Base64URL-encoded, making it suitable for HTTP headers, cookies, and URLs.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

   Header          Payload              Signature
(algorithm)    (user claims)       (verification hash)

JWT Structure Decoded

Header

The header identifies the algorithm used to sign the token:

{
  "alg": "HS256",    // Algorithm: HMAC-SHA256
  "typ": "JWT"       // Token type
}

Payload (Claims)

The payload contains claims — statements about the user and metadata:

{
  "sub": "1234567890",      // Subject (user ID)
  "name": "John Doe",       // Custom claim
  "email": "john@example.com",
  "role": "admin",           // Custom claim
  "iss": "https://api.example.com",  // Issuer
  "aud": "https://app.example.com",  // Audience
  "iat": 1516239022,        // Issued at (Unix timestamp)
  "exp": 1516242622         // Expiration (1 hour later)
}

Signature

The signature ensures the token has not been tampered with:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret_key
)

How JWT Authentication Works

JWT vs Session-Based Auth

Common JWT Claims

Security Best Practices

• Always verify signatures — Never trust a JWT without verification. Use a well-tested library.
• Use short expiration times — Set exp to 15-60 minutes. Use refresh tokens for longer sessions.
• Store in httpOnly cookies — Prevents XSS attacks from reading the token. Add Secure and SameSite flags.
• Never store sensitive data in payload — JWT payloads are Base64-encoded, not encrypted. Anyone can decode them.
• Use strong secrets — For HMAC, use at least 256 bits of randomness. For RSA/EC, use proper key sizes.
• Implement token revocation — Use a blacklist or short-lived tokens with refresh tokens.

Common JWT Vulnerabilities

Implementation Example

// Node.js with jsonwebtoken library
const jwt = require('jsonwebtoken');

// Sign (create token)
const token = jwt.sign(
  { sub: user.id, name: user.name, role: user.role },
  process.env.JWT_SECRET,
  { expiresIn: '1h', issuer: 'https://api.example.com' }
);

// Verify (validate token)
try {
  const decoded = jwt.verify(token, process.env.JWT_SECRET, {
    issuer: 'https://api.example.com',
    algorithms: ['HS256'],  // Prevent alg switching!
  });
  console.log(decoded.sub); // User ID
} catch (err) {
  // Token is invalid or expired
  console.error('JWT verification failed:', err.message);
}

// Express middleware
function authMiddleware(req, res, next) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'No token provided' });
  }
  const token = authHeader.split(' ')[1];
  try {
    req.user = jwt.verify(token, process.env.JWT_SECRET);
    next();
  } catch {
    return res.status(401).json({ error: 'Invalid token' });
  }
}

FAQ