How a JWT works

· 2 min read

#how-it-works#security

A JWT (JSON Web Token) is a compact string that carries claims, such as who issued a token and when it expires. The idea to keep: the signature protects the token from changes, but it does not hide what is inside.

The short version

A signed JWT has three parts joined by dots: a header, a payload and a signature. The header names the signing algorithm in alg, and the payload holds the claims. Both are base64url encoded. That is an encoding, not encryption, so anyone holding the token can decode and read them (my inference from how the encoding works). The signature is computed over the first two encoded parts, so changing either one breaks it.

How a JWT is made and checked Top row, left to right: header and payload, then signing, then the finished token. Arrow 3 goes down from the token to the receiver's signature check. Dashed arrows then lead left to the claims check and finally to accept or reject. Header + payload two JSON objects Sign with the alg in header Token three parts, two dots Recheck signature with your own alg Check the claims exp, iss, aud Accept or reject any failure rejects 1 2 3 4 5
Simplified: only signed tokens are shown, not encrypted ones.

Step by step

  1. The sender builds the header and the payload as JSON.
  2. It base64url encodes both and joins them with a dot.
  3. It signs that text with the algorithm named in alg.
  4. The token is the two parts plus the signature, with dots between them.
  5. The receiver recomputes the signature, then checks exp, iss and aud.
Part Holds Used for
Header alg, typ which algorithm signed the token
Payload iss, sub, aud, exp, iat issuer, subject, audience, expiry, issue time
Signature the computed signature catching changes

Why it matters

Trust no claim until the signature checks out, and take the algorithm from your own settings, not from the token's header. RFC 8725 warns about tokens with alg set to none, which carry no signature. The upside is a compact token that fits in a URL; the downside is that anyone can read it, and a careless check can be fooled.

Sources