JWT Structure & Signing Algorithms

#Introduction

A JSON Web Token (JWT) is a compact, URL-safe string that carries claims — statements about a user, such as their username, roles and when the token expires. JWTs are the "passports" of modern web APIs: the server issues one at login, and the client presents it on every request.

JWT signatures use cryptographic algorithms to prove the token hasn't been tampered with and was issued by someone holding the key.

#JWT Structure

A JWT has three parts separated by dots:

Header.Payload.Signature

eyJhbGciOiJIUzI1NiJ9
.
eyJzdWIiOiJyYWoiLCJyb2xlIjoiVVNFUiJ9
.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

1. Header

Token metadata:

{
  "alg": "HS256",
  "typ": "JWT"
}

alg is the signing algorithm and typ the token type.

2. Payload

The claims:

{
  "sub": "thimmaraju",
  "role": "ADMIN",
  "iat": 1716000000,
  "exp": 1716003600
}

sub, iat, exp, nbf, iss, aud and jti are registered claims defined by the JWT standard (RFC 7519); anything else, like role or email, is a custom claim.

3. Signature

The most important part:

HMACSHA256(
    Base64Url(Header) + "." + Base64Url(Payload),
    secretKey
)

Its purpose is to prevent tampering and verify authenticity.

#Base64URL Is Encoding, Not Encryption

The header and payload are only Base64URL-encoded — a reversible, URL-safe text encoding. Anyone can decode them (for example on jwt.io):

{
  "username": "raj",
  "role": "ADMIN"
}

#How Token Generation Works (HS256)

Suppose the secret key is a 256-bit key, the header is {"alg":"HS256","typ":"JWT"} and the payload is {"username":"raj"}.

Step 1 — Base64URL-encode both parts:

Header:  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Payload: eyJ1c2VybmFtZSI6InJhaiJ9

Step 2 — join them with a dot:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InJhaiJ9

Step 3 — apply HMAC-SHA256 with the secret key → signature.

Final JWT: header.payload.signature.

What Is HMAC?

Plain SHA256("hello") produces a hash that anyone can compute, so it can't prove who created a token. HMAC mixes a secret key into the hash:

HMACSHA256(message, secretKey)

Without the secret key, nobody can produce a valid signature.

HS256 = HMAC + SHA-256: HMAC (Hash-based Message Authentication Code) using SHA-256, a hash with a 256-bit output.

#How Verification Works

Why Can't Someone Change the Payload?

Original payload {"role":"USER"} — an attacker changes it to {"role":"ADMIN"}. They can edit it, because Base64 isn't encryption. But header.payload has changed, so the original signature no longer matches, and the attacker can't compute a new one without the key. Verification fails with a SignatureException and the token is rejected.

#Signing Algorithms

HMAC — Symmetric (HS256, HS384, HS512)

One shared secret both signs and verifies:

Pros: fast and simple. Cons: every service that verifies tokens must also hold the secret — and anyone who can verify can also forge tokens.

RSA — Asymmetric (RS256, RS384, RS512)

A private key signs; a public key verifies:

Advantages: the public key can be shared safely (often published as a JWKS endpoint), the private key never leaves the auth server, and verifying services can't forge tokens. Used by OAuth2, OpenID Connect and identity providers such as Keycloak, Okta, Auth0 and Azure AD.

ECDSA — Asymmetric (ES256, ES384, ES512)

Uses elliptic-curve cryptography: much smaller keys and signatures than RSA for the same security, and fast verification. Common in mobile apps and modern identity systems.

Which Algorithm Should You Use?

#HS256 vs RS256

#Example with JJWT

JJWT 0.12+ (the current API):

SecretKey key = Keys.hmacShaKeyFor(Decoders.BASE64.decode(secretBase64));   // ≥ 256-bit key

String token = Jwts.builder()
        .subject("raj")
        .claim("role", "ADMIN")
        .issuedAt(new Date())
        .expiration(new Date(System.currentTimeMillis() + 3_600_000))   // 1 hour
        .signWith(key)                     // algorithm chosen from the key: HS256 for a 256-bit key
        .compact();

Claims claims = Jwts.parser()
        .verifyWith(key)                   // signature verified with this key
        .build()
        .parseSignedClaims(token)          // throws if tampered with or expired
        .getPayload();

What Does .signWith(key) Do?

It creates a digital signature for the JWT from the encoded header and payload using the key — HMAC-SHA256 for a 256-bit secret key — guaranteeing the token's integrity and authenticity. Without the key, nobody can create a valid token or modify an existing one.

#Key Takeaways

• A JWT is header.payload.signature; header and payload are Base64URL-encoded JSON.
• The signature guarantees integrity and authenticity, not confidentiality.
• HS256 uses one shared secret (≥ 256 bits); RS256/ES256 sign with a private key and verify with a public key.
• Prefer RS256 when many services verify tokens.
• Use the JJWT 0.12 API: subject(), signWith(key), parser().verifyWith(key), parseSignedClaims().