OAuth 2.0 and JWT Explained: What Really Happens When You Click "Sign In"

Part 1 of 19 · ~3 min

Overview

Tasklight, Priya and the incidents in this guide are invented to teach with.

Priya is onboarding onto her team's new project tracker, Tasklight. The login screen has exactly one button: Sign in with Kestrel. She clicks it, a login page appears — hosted at id.kestrel.example, not at Tasklight's own domain — she types her Kestrel password into a form there, and a few seconds later she's looking at her team's board, logged in.

Here's the assumption almost everyone quietly carries away from a moment like that: Tasklight now has her password, or something equivalent to it, sitting in a database somewhere. It felt like logging in. Except Tasklight never saw that password. Not encrypted, not hashed, not held in memory for a millisecond — it genuinely never touched anything Tasklight controls. What Tasklight is holding, a few seconds after that click, is something much narrower: a short-lived, specifically-scoped credential that says this app may act as this particular person, for these particular things, for this particular window of time — and nothing about Priya's actual password. Getting from "Priya typed a password into a form" to "Tasklight is holding that credential instead" is the entire subject of this reference.

That gap — between what people assume their app just received and what it actually received — is where OAuth 2.0 and JWTs live, and it is a genuinely deep gap: the mechanism behind it has to survive phishing attempts, stolen laptops, copy-pasted tokens, and a determined attacker with a network sniffer, not just the happy path. So we're going to build the whole thing around one real product, start to finish: Tasklight, and the five distinct ways it ends up talking to its identity provider.

There's a web app — the one Priya just used, running server-rendered pages from a backend nobody outside Tasklight can reach into. There's a CLI tool developers run from their terminal, which can't keep a secret, because anything shipped to a user's machine can be pulled out of it. There's a dashboard bolted to a TV on the office wall, which has no keyboard worth typing a password into. There's a nightly job that emails admins a usage report, which involves no human at all. And there's a small embeddable widget customers can drop into their own marketing site, which has no backend of its own whatsoever. Four of those five need a completely different flow than Priya's web login used, for reasons that will turn out to matter a great deal — and the fifth is where a very real security trade-off shows up with nowhere left to hide.

By the end of this reference, Priya's one click will have produced a code that expires in under a minute, a signed token Tasklight's own backend is obligated to verify rather than trust on sight, and a second, much longer-lived credential she never sees at all. Work through this front to back if you can — the five client surfaces build on each other — or jump to whatever you're stuck on; every chapter opens by naming which part of Tasklight it's working on.