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
| Claim | Purpose |
|---|---|
iss | Who created the token |
sub | Who the token is about |
aud | Who should accept it |
exp | When 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
- The auth server signs
header.payloadwith its private key - Snowflake splits the token and recomputes with the public key
- If the signatures match, the token is authentic and untampered
Snowflake External OAuth
Each claim must match the security integration
| Claim | Maps to |
|---|---|
iss | external_oauth_issuer, exactly |
aud | external_oauth_audience_list, exactly |
scp | Snowflake role, e.g. session:role:ANALYST |
name | A 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_NAMEexactly
The trade-off
Stateless scales well, but revocation is hard
| JWT | Session token | |
|---|---|---|
| State | Self-contained | Server stores session |
| Revocation | Wait for expiry | Delete the session |
| Scalability | No shared store | Needs 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