JWT validation and token storage

A service receives a token that claims "role": "admin". Whether to believe it is the whole question of JWT validation. A JWT is three base64url strings that anyone can read and anyone can write, so in this lesson’s first program a service that only decodes believes all four tokens it is shown, two of them forged, and a service that verifies accepts one.

In short: verify the signature with a key you chose and an algorithm you allow, then check the issuer, the audience, the time window and the type. Where the token lives afterwards is a second question, token storage, because each place a browser app can keep a token has different readers. This lesson covers both, and the bugs that skip the checks.

A token can be read by anyone, so a service must check it before it believes it

A JWTJWT: JSON Web Token (RFC 7519): three base64url parts joined by dots, a header, a payload of claims and a signature. The payload is encoded and not encrypted, so anyone who holds a token can read it. carries a header, a payload of claims and a signature. The payload is encoded and not encrypted, so anyone who holds a token can read its claims, and anyone can write a token with claims of their choice. JWT validation is what tells the two apart: it proves that the issuer signed these exact claims, and that this service is the one meant to read them. Step through the order in which a service makes its checks:

JWT validation has seven parts, and a service that skips any one of them has a bug that a test can show:

• Signature. The service recomputes it with the key it trusts and refuses a token whose signature does not match.
• Algorithm. The token’s alg must be on the service’s own list, and none is never on it.
• Key. The key comes from the service’s own list, found by the token’s kid, and a key inside the token is never used.
• Issuer. The iss claim must name the issuer that the service trusts.
• Audience. The aud claim must name this service, so a token made for another API is refused.
• Time. The token must be inside its nbf and exp window, allowing a small leeway for clocks.
• Type. The typ header must say what kind of token it is, so an ID token cannot pass as an access token.

The first program makes four tokens, one genuine and three that are not, and prints what a decoder and a verifier say about each:

"""Decoding a JWT only reads it. Verifying it with the key is what makes its claims worth believing."""

import base64
import hashlib
import hmac
import json

KEY = b"lab key of the orders service: never use a key like this"
OTHER_KEY = b"a key that the sender made up"
NOW = 1_000_000  # seconds on the lab's own clock


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


def unb64u(text):
    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))


def encode(obj):
    return b64u(json.dumps(obj, separators=(",", ":"), sort_keys=True).encode())


def make(payload, key):
    signing_input = f"{encode({'alg': 'HS256', 'typ': 'JWT'})}.{encode(payload)}"
    return f"{signing_input}.{b64u(hmac.new(key, signing_input.encode(), hashlib.sha256).digest())}"


def decode_only(token):
    """Reads the payload. Anyone can do this: it is base64url text, not encrypted."""
    return json.loads(unb64u(token.split(".")[1]))


def verify(token, key, now):
    """Checks the signature with the key first, and only then looks at the claims."""
    head, body, signature = token.split(".")
    expected = hmac.new(key, f"{head}.{body}".encode(), hashlib.sha256).digest()
    if not hmac.compare_digest(expected, unb64u(signature)):
        return None, "bad signature"
    claims = json.loads(unb64u(body))
    if now > claims["exp"]:
        return None, "expired"
    return claims, None


genuine = make({"sub": "asha", "role": "member", "exp": NOW + 900}, KEY)
head, _, signature = genuine.split(".")
edited = f"{head}.{encode({'sub': 'asha', 'role': 'admin', 'exp': NOW + 900})}.{signature}"
expired = make({"sub": "asha", "role": "member", "exp": NOW - 60}, KEY)
other_key = make({"sub": "asha", "role": "admin", "exp": NOW + 900}, OTHER_KEY)

print("what anyone can read in the genuine token:", decode_only(genuine))
print()
print(f"{'token':<30}{'decode only says':<20}verify says")
for name, token in [("genuine", genuine), ("payload edited, old signature", edited), ("expired", expired), ("signed with another key", other_key)]:
    claims = decode_only(token)
    said = f"{claims['sub']}, {claims['role']}"
    checked, reason = verify(token, KEY, NOW)
    answer = f"accepted: {checked['sub']}, {checked['role']}" if checked else f"refused: {reason}"
    print(f"{name:<30}{said:<20}{answer}")

what anyone can read in the genuine token: {'exp': 1000900, 'role': 'member', 'sub': 'asha'}

token                         decode only says    verify says
genuine                       asha, member        accepted: asha, member
payload edited, old signature asha, admin         refused: bad signature
expired                       asha, member        refused: expired
signed with another key       asha, admin         refused: bad signature

The decoder reported admin for the two forged tokens, because it believes what it reads. The verifier accepted only the genuine one: the edited payload and the token signed with another key failed the signature, and the expired one failed its exp.

Token storage is the other half. localStorage and sessionStorage are open to every script of the page. A variable in memory is lost at every reload. An HttpOnly cookie is hidden from scripts, and the browser sends it with requests on its own. A backend for frontendbackend for frontend (BFF): A server component between a browser app and the APIs it calls. It runs the sign-in flow and keeps the app's tokens itself, so that the browser holds only a session cookie and no token. More in “OAuth 2.0 and OpenID Connect: done right” keeps the token on the server, so there is nothing in the browser to read. Each place has its own readers.

Seven checks against fifteen tokens: a first draft and a fixed verifier Pro: opens with a Pro, Premium or Ultimate pass