JWT — JSON Web Tokens

What is a JWT — and Why Does it Exist?

A JWT (JSON Web Token) is a signed, self-contained claim about an identity — the token itself carries enough information (who the subject is, what roles they have, when it expires) that a server can verify it's authentic and act on it without looking anything up. This is the direct answer to the scaling problem described on the previous page: a session requires every instance to query a shared store on every request; a JWT only requires verifying a cryptographic signature, which needs no network call and no shared infrastructure at all. That's exactly why JWTs are the default choice for authenticating calls between microservices — an inventory service receiving a request from an order service can verify the caller's claims using only a public key it already has, with zero coupling to whatever system originally issued the token.

The trade-off, covered in full at the end of this page, is the one already previewed on the Session Management page: no shared store means no instant server-side revocation. Everything else about how JWTs are built, signed, and stored follows from a single fact worth stating plainly up front: a JWT is signed, not encrypted. Its payload is base64url-encoded — trivially readable by anyone who intercepts it — and the signature only proves the claims weren't tampered with after issuance, not that they're secret.

// BEFORE — every request pays for a network round-trip to a shared session store
// just to answer "who is this and what are they allowed to do?"
SessionData session = redisTemplate.opsForValue().get("session:" + sessionId);
if (session == null || session.isExpired()) {
    throw new BadCredentialsException("Invalid or expired session");
}
// Every service in the chain (order-service, inventory-service, shipping-service)
// needs network access to the SAME Redis instance to answer this question.

// AFTER — verification is a local, offline cryptographic operation
Claims claims = Jwts.parser()
    .verifyWith(publicKey)          // only needs the ISSUER's public key — never a shared secret store
    .build()
    .parseSignedClaims(token)
    .getPayload();
// No network call. No shared store. Any service holding the public key can
// verify this independently — that's the entire point.

Anatomy of a JWT — Three Base64url Segments, Not Encryption

/*
 * A JWT is three base64url-encoded segments joined by dots:
 *
 *   eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MjIiLCJyb2xlIjoiQ1VTVE9NRVIi...}.dBjftJeZ4CVP-mB92K...
 *   └──────────── header ────────────┘ └──────────── payload ────────────┘ └── signature ──┘
 *
 * HEADER (decoded):     {"alg": "RS256", "typ": "JWT"}
 * PAYLOAD (decoded):    {"sub": "422", "role": "CUSTOMER", "iat": 1751000000, "exp": 1751003600}
 * SIGNATURE:            RSA-SHA256(base64url(header) + "." + base64url(payload), privateKey)
 *
 * base64url is an ENCODING, not encryption. Anyone can decode the header and
 * payload with zero cryptographic knowledge — paste any JWT into a decoder and
 * read every claim in plaintext. The signature's only job is proving the
 * header+payload weren't modified after the issuer signed them.
 */

Standard Claims

Signing Algorithms — Symmetric (HMAC) vs Asymmetric (RSA/EC)

@Service
public class JwtService {

    private final PrivateKey signingKey;      // held ONLY by the issuing service
    private final PublicKey verificationKey;

    public JwtService(PrivateKey signingKey, PublicKey verificationKey) {
        this.signingKey = signingKey;
        this.verificationKey = verificationKey;
    }

    public String generateToken(Authentication auth) {
        Instant now = Instant.now();
        return Jwts.builder()
            .subject(auth.getName())
            .claim("role", extractRole(auth))
            .issuer("https://auth.shop.example.com")
            .audience().add("order-service").and()
            .issuedAt(Date.from(now))
            .expiration(Date.from(now.plus(Duration.ofMinutes(15))))   // short-lived access token
            .signWith(signingKey, Jwts.SIG.RS256)
            .compact();
    }

    public Claims parseAndValidate(String token) {
        return Jwts.parser()
            .verifyWith(verificationKey)
            .requireIssuer("https://auth.shop.example.com")
            .requireAudience("order-service")
            .build()
            .parseSignedClaims(token)
            .getPayload();   // throws ExpiredJwtException / SignatureException on any failure — never swallow these
    }
}

Two Vulnerabilities That Come Directly From How JWTs Are Structured

1. The "alg": "none" Trap

/*
 * The JWT spec permits an "none" algorithm for genuinely unsecured use cases.
 * Some early JWT libraries honored whatever "alg" the ATTACKER put in the
 * header — including "none" — and skipped signature verification entirely.
 *
 * Attack: take a legitimate token, change the header to {"alg":"none"},
 * change any claim (e.g. "role":"CUSTOMER" → "role":"ADMIN"), drop the
 * signature segment entirely. A vulnerable verifier accepts it as valid.
 */

// THE FIX: never let the token's own header dictate which algorithm verifies
// it — pin the expected algorithm explicitly at verification time
Claims claims = Jwts.parser()
    .verifyWith(verificationKey)
    // Modern JJWT (and most current libraries) require you to configure the
    // accepted algorithm(s) up front via the key type — an RSA PublicKey here
    // means ONLY RS256/RS384/RS512 signatures are ever accepted, "none" and
    // HS256 are rejected outright rather than silently trusted from the header.
    .build()
    .parseSignedClaims(token)
    .getPayload();

2. Algorithm Confusion — RS256 Downgraded to HS256

/*
 * If a verifier is written to accept "whatever alg the token header claims"
 * rather than a fixed expected algorithm, a second attack becomes possible:
 *
 * 1. The legitimate system signs with RS256 (private key signs, public key
 *    verifies) and publishes its RSA PUBLIC key openly, as intended.
 * 2. An attacker crafts a forged token with header {"alg":"HS256"} and signs
 *    it using an HMAC secret equal to... the RSA public key's bytes.
 * 3. A verifier that naively does "look at alg in the header, then verify
 *    using whatever key I have configured, treating it as that algorithm's
 *    key type" ends up computing HMAC-SHA256(header.payload, publicKeyBytes)
 *    — and since the public key is, by definition, public, the attacker CAN
 *    compute that exact same HMAC and produce a signature that validates.
 */

// THE FIX is the same discipline as above: the verifier must hardcode which
// algorithm family it expects for a given key, never derive it from the
// token's own header. This is precisely why modern JWT libraries tie key
// TYPE to algorithm — an RSA PublicKey object simply cannot be handed to an
// HMAC verification path in a well-designed API.

Client-Side Storage — localStorage vs an HttpOnly Cookie

This decision gets debated constantly, and the honest answer is that both options trade one risk for a different one — there is no zero-risk choice, only an explicit one.

// Issue the JWT as an HttpOnly, Secure, SameSite=Strict cookie rather than a
// JSON field the client is expected to store itself
@PostMapping("/login")
public ResponseEntity<Void> login(@RequestBody LoginRequest request) {
    Authentication auth = authManager.authenticate(
        new UsernamePasswordAuthenticationToken(request.username(), request.password())
    );
    String token = jwtService.generateToken(auth);

    ResponseCookie cookie = ResponseCookie.from("access_token", token)
        .httpOnly(true)          // unreachable from JavaScript, even via a successful XSS payload
        .secure(true)            // never sent over a plain HTTP connection
        .sameSite("Strict")     // not attached to cross-site requests — this is what mitigates CSRF here
        .path("/")
        .maxAge(Duration.ofMinutes(15))
        .build();

    return ResponseEntity.ok().header(HttpHeaders.SET_COOKIE, cookie.toString()).build();
}

Access + Refresh Tokens — Living With No Instant Revocation

A stateless token can't be individually revoked before its expiry without reintroducing some form of shared state — which is exactly the dependency JWTs exist to avoid. The practical mitigation is to keep the access token short-lived (minutes, as shown above) and pair it with a longer-lived refresh token that is itself tracked and revocable, since it's checked against a store on every use rather than trusted purely on its signature.

@PostMapping("/refresh")
public ResponseEntity<Void> refresh(@CookieValue("refresh_token") String refreshToken) {
    // Refresh tokens ARE looked up against a store — this is the deliberate
    // point where revocability re-enters the design, in exchange for one
    // lookup per refresh instead of one lookup per request.
    RefreshTokenRecord record = refreshTokenRepository.findByToken(refreshToken)
        .filter(r -> !r.isRevoked() && r.getExpiresAt().isAfter(Instant.now()))
        .orElseThrow(() -> new BadCredentialsException("Invalid or expired refresh token"));

    // Rotate on every use: revoke the old refresh token, issue a new one.
    // This limits the damage of a stolen refresh token to a single use window
    // and makes reuse of an already-rotated token a detectable signal of theft.
    record.revoke();
    refreshTokenRepository.save(record);
    String newAccessToken = jwtService.generateToken(record.toAuthentication());
    String newRefreshToken = refreshTokenService.issue(record.getUsername());

    // ... set both as HttpOnly/Secure/SameSite cookies, same as login
    return ResponseEntity.ok().build();
}

Best Practices and Common Pitfalls

Interview Questions