Login Flow Diagram Guide

A login flow diagram shows how an anonymous request turns into an identified one. Not "how the password is checked" — that part is one arrow and a library call. What the diagram is actually about is the thing handed back afterwards, how long it lives, where it is stored, and what invalidates it.

Almost every login diagram on the internet is the same picture: a box for the form, a diamond that says credentials correct?, a green arrow to "Dashboard" and a red arrow back to "Login". That picture is not wrong, it is just answering a question nobody has. Nobody is confused about whether a wrong password should let you in. What people are confused about — and what breaks in production — is everything the diamond leaves out: what got created on the yes branch, how many times you can take the no branch before something happens, and whether the two branches are distinguishable from the outside.

That last point is why this is usually a sequence diagram rather than a flowchart. A flowchart draws your server's reasoning. A sequence diagram draws what crosses the wire, which is the only thing an attacker can see, and therefore the only thing worth reviewing. The moment you draw responses as arrows instead of outcomes as boxes, "user not found" and "wrong password" stop being two branches of your logic and become two strings a stranger can tell apart.

This page draws the password path. The second factor and the sign-in-with-Google button attach to it at a single point each, and each has its own page — folding them in here would produce a diagram with three beginnings.

Six things. If your diagram has the diamond but not these, it is a picture of a form, not of a login.

Here is the skeleton — the version everybody draws, with none of the six on it. It is worth looking at precisely because it looks finished. Every arrow in it is correct; the diagram is still useless for review, because nothing here can be wrong in an interesting way.

Three steps. The first one is a reordering, and it is most of the value.

Start at the end. Before you draw a single arrow of the form, write down what exists after a successful login that did not exist before:

- a row somewhere, or a signed token with nothing behind it - an identifier delivered to the browser, with a specific set of cookie attributes - an expiry — and probably two: an idle one and an absolute one - a list of things that destroy it early

Now work backwards. The credential check exists to authorise creating that object, and once you see it in that order the diagram writes itself: the check is a guard, and everything interesting is on the other side of it.

Doing it the usual way — form, diamond, done — produces diagrams where the session is implied by an arrow labelled "success". That label is where lifetime bugs hide, because nothing on the page ever forced anyone to say how long "success" lasts.

List every way this can go wrong, then draw them all arriving at one arrow:

- no account with that email - account exists, wrong password - account exists, correct password, but disabled or unverified - too many attempts

Only the last one is allowed to look different, and only because it has to — you cannot rate-limit someone without telling them. Everything else gets the same status code, the same message, and ideally the same latency.

This is the step people skip, and skipping it is not a subtle mistake. A signup form that says "this email is already registered" combined with a login that says "no account with that email" is a free membership-checking API: feed it a leaked address list and it tells you who has an account here. Both messages are individually helpful and jointly a disclosure, which is exactly the kind of thing a diagram catches and a code review does not, because the two strings live in different files written months apart.

If your product genuinely needs to tell users their account is disabled, do it after the password is verified — at that point you are talking to the account owner, not to a stranger. On the diagram that is one arrow moved below a branch, and it is the whole fix.

Describe it in sentences and let text2diagram lay it out — "the user posts an email and password, the service rate limits by email and by IP, loads the user, verifies the hash even when no user exists, and on success creates a 30-day session and sets an HttpOnly cookie; every failure returns the same 401" comes back as an editable sequenceDiagram with the alt blocks already nested correctly.

Or open one of the three below and rename the participants. The branch structure is the part worth keeping.

Three diagrams covering the three questions a login design actually has to answer: what happens at the door, what the thing you were given is worth over time, and how someone gets back in without it.

Four details here are the reason to copy this one rather than draw your own from memory.

The rate limit is before the database lookup, and it names both subjects. Putting it after means an attacker still gets a free query per attempt, which is the expensive part.

run it even when there is no row looks like a note to an implementer, and it is, but it is also the difference between a login endpoint and a user-existence endpoint. Skip it and the timing tells the whole story.

The session arrow carries its attributes and its lifetime. That single label has settled more design arguments than any paragraph of prose next to it.

And the failure branch merges: no row and wrong password produce the same arrow, deliberately drawn as one. If you can find two distinguishable failure arrows in your own diagram, you have found a bug without running anything.

A state diagram, because this part is not a conversation — it is one object aging. Drawing it separately is what stops "session" from being a word on an arrow.

The two expiries are the point. Idle is a sliding window that resets on every request; absolute does not reset, ever. Systems with only the sliding one issue sessions that live forever as long as a tab is open somewhere. Systems with only the absolute one log people out mid-task at an arbitrary moment. Almost everyone wants both, and almost nobody writes both down.

Revoked is the transition worth arguing about in review. When a user changes their password because they think someone else has it, the only response that matches their intent is killing every session everywhere — including the attacker's. If your diagram has no arrow from password changed to Revoked, then changing the password does nothing to whoever is already inside.

Draw this next to the login diagram, not in a separate document, because it grants exactly what login grants and is usually protected far less carefully.

The first response is the whole design in one arrow: 200 regardless of whether the account exists, sent before anything is looked up. Every other ordering leaks. The user-facing text has to match — "if that email is registered we sent a link" — and yes, it is slightly worse copy. It is also the only wording that does not turn this form into the enumeration endpoint your login page refused to be.

The token is single-use and short-lived, and the reason both matter is that reset links land in mailboxes, which get forwarded, backed up, and synced to devices nobody remembers owning.

The revocation arrow is the one most implementations forget. Someone resetting their password is very often someone who has already been compromised. If old sessions survive the reset, the reset accomplished nothing at all.