JWT: Structure, Signing, Validation

By the end of this lesson you can:

• Decode a JWT's three parts: header, payload (claims), signature.
• Create and verify JWTs with PyJWT, always checking the signature + expiry.
• Avoid the classic JWT pitfalls: alg:none, unverified decode, secrets in the payload.
• Choose appropriate claims, expiry, and a strong signing key.

eyJhbGciOiJ...  .  eyJzdWIiOiJ...  .  SflKxwRJSM...
   HEADER             PAYLOAD            SIGNATURE
(alg + type)     (the claims, e.g.    (proves header+payload
                  user id, role,       weren't altered, and
                  expiry)              who issued it)

The three parts

HEADER    {"alg": "HS256", "typ": "JWT"}      ← which signing algorithm
PAYLOAD   {"sub": 1, "role": "user",          ← the CLAIMS (readable!)
           "exp": 1716900000}                  ← standard: exp, iat, iss, sub
SIGNATURE HMAC-SHA256(base64(header) + "." +   ← over header+payload, with the
          base64(payload), SECRET_KEY)          secret → can't forge without it
Token = base64(header).base64(payload).signature

The signature is computed over the header and payload using the secret key. Change one character of the payload and the signature no longer matches — so tampering is detected (integrity, Lesson 17). But the payload is just base64, not encryption.

Create & verify with PyJWT

import jwt, os, datetime      # pip install pyjwt
SECRET = os.environ["JWT_SECRET"]      # strong, from env (never hard-coded)

# CREATE (on login): sign the claims
def make_token(user_id: int, role: str) -> str:
    payload = {
        "sub": user_id,
        "role": role,
        "iat": datetime.datetime.now(datetime.timezone.utc),
        "exp": datetime.datetime.now(datetime.timezone.utc)
               + datetime.timedelta(minutes=15),     # short expiry
    }
    return jwt.encode(payload, SECRET, algorithm="HS256")

# VERIFY (on each request): check signature, expiry, algorithm
def verify_token(token: str) -> dict:
    return jwt.decode(token, SECRET, algorithms=["HS256"])  # raises if invalid

jwt.decode with the secret and an explicit algorithms list verifies the signature and the expiry, raising on any problem. That verification is the whole point — never skip it.

⚠️ The classic JWT pitfalls

Claims & expiry hygiene

• Short expiry (exp) — minutes for access tokens, with a refresh-token flow for longer sessions. This limits the damage of a stolen token (which you can't easily revoke).
• Don't put secrets in claims — the payload is readable. User id and role, yes; passwords, API keys, PII, no.
• Verify the issuer/audience (iss, aud) when relevant, to reject tokens meant for another service.
• Revocation is hard — for logout/ban, keep a short expiry plus a server-side denylist of revoked token IDs (jti) if you need instant revocation.

HS256 vs RS256

HS256 uses one shared secret to sign and verify (simple, fine when the same party does both). RS256 signs with a private key and lets others verify with the public key (Lesson 16) — better when many independent services need to verify but not issue tokens. Don't let an attacker switch your RS256 to HS256 (algorithm confusion) — the explicit algorithms list prevents it.

Goal: issue a JWT, verify it, then show that editing the payload to escalate privileges fails verification — proving the signature does its job. (And show the dangerous "unverified decode" for contrast.)

import jwt, datetime, base64, json

SECRET = "a-long-random-demo-secret-from-env-in-real-life"

def make_token(uid, role):
    return jwt.encode({
        "sub": uid, "role": role,
        "exp": datetime.datetime.now(datetime.timezone.utc)
               + datetime.timedelta(minutes=15),
    }, SECRET, algorithm="HS256")

token = make_token(1, "user")
print("issued:", token[:40], "...")

# anyone can READ the payload (it's NOT encrypted):
payload_b64 = token.split(".")[1] + "=="          # pad for base64
print("readable payload:", json.loads(base64.urlsafe_b64decode(payload_b64)))

# correct verification:
print("verified:", jwt.decode(token, SECRET, algorithms=["HS256"]))

# ATTACK: tamper with the payload to claim role=admin, keep old signature
import copy
header, body, sig = token.split(".")
evil_body = base64.urlsafe_b64encode(
    json.dumps({"sub": 1, "role": "admin"}).encode()).rstrip(b"=").decode()
forged = f"{header}.{evil_body}.{sig}"            # signature no longer matches body
try:
    jwt.decode(forged, SECRET, algorithms=["HS256"])
except jwt.InvalidSignatureError:
    print("forged token REJECTED — signature doesn't match ✓")

# the DANGEROUS anti-pattern (NEVER do this):
print("unverified (DANGER):",
      jwt.decode(forged, options={"verify_signature": False}))  # trusts role=admin!

issued: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ...
readable payload: {'sub': 1, 'role': 'user', 'exp': 1716900900}
verified: {'sub': 1, 'role': 'user', 'exp': 1716900900}
forged token REJECTED — signature doesn't match ✓
unverified (DANGER): {'sub': 1, 'role': 'admin'}    ← privilege escalation if you skip verify!

Read the code

Three lessons in one demo. First, the payload is plainly readable (base64, not encryption) — so it must never hold secrets. Second, the attacker's attempt to change role to admin is rejected, because editing the payload invalidates the signature they can't recompute without the secret — that's the integrity guarantee working. Third, the "DANGER" line shows the catastrophe of skipping verification: verify_signature=False happily returns role: admin from the forged token. The rule is absolute: always verify, with an explicit algorithms list.

A JWT is three base64 parts — header, payload (claims), signature — joined by dots. It's signed, not encrypted: the payload is readable, so never put secrets in it; security comes from the signature, which detects tampering. Create with jwt.encode, and always verify with jwt.decode(token, secret, algorithms=[...]) — the explicit algorithm list defeats the alg:none and algorithm-confusion attacks, and exp is checked automatically. Never skip verification (it lets attackers forge role:admin). Use short expiry + refresh for revocation, a strong secret from the environment, and consider RS256 when many services must verify but not issue.