How JWTs work

Not an opaque blob: three parts you can read and verify

What a JWT carries, why it can be trusted, and how Snowflake External OAuth uses it.

Kevin Keller · kevinkeller.org

Why it matters

Every OAuth flow and modern SSO system runs on JWTs

Most developers copy a token, paste it into a header and move on. Knowing what is inside is how you avoid the security pitfalls.

Anatomy

Header, payload, signature, separated by dots

  • Header: the algorithm and token type, such as RS256
  • Payload: claims about the user, such as iss, sub, aud, exp
  • Signature: proof the first two parts weren't changed
  • Change one character and the signature no longer matches

The first rule

The payload is encoded, not encrypted

Anyone who has the token can read the payload. Never put secrets in it.

The claims that matter

Who issued it, for whom, and until when

ClaimPurpose
issWho created the token
subWho the token is about
audWho should accept it
expWhen it expires: without it, a stolen token works forever

Why JWTs scale

Verification is entirely local

The API holds the public key and checks the signature itself. No round trip to the auth server, no session store.

Signing with RS256

The private key never leaves the auth server

  1. The auth server signs header.payload with its private key
  2. Snowflake splits the token and recomputes with the public key
  3. If the signatures match, the token is authentic and untampered

Snowflake External OAuth

Each claim must match the security integration

ClaimMaps to
issexternal_oauth_issuer, exactly
audexternal_oauth_audience_list, exactly
scpSnowflake role, e.g. session:role:ANALYST
nameA Snowflake LOGIN_NAME

Security pitfalls

Five ways JWTs go wrong

  • alg: none: validate the algorithm server-side
  • Weak or exposed keys: 2048-bit+ RSA, kept in a vault, rotated
  • No expiry: keep access tokens to 15 to 60 minutes
  • Audience confusion: always set a specific aud
  • User mapping errors: match LOGIN_NAME exactly

The trade-off

Stateless scales well, but revocation is hard

JWTSession token
StateSelf-containedServer stores session
RevocationWait for expiryDelete the session
ScalabilityNo shared storeNeeds a shared store
Size~800+ bytes~32 bytes

The takeaway

Readable by anyone, trusted only when the signature checks out.

Read the full article · Try the JWT Playground

Kevin Keller · kevinkeller.org