How to Diagram a User Authentication Flow

Authentication seems simple until you draw it. A user types a password and gets in - but behind that sit sessions, tokens, expiry, refresh, third-party providers, multi-factor prompts, and a dozen ways each can fail. Most authentication vulnerabilities are not exotic cryptographic breaks; they are ordinary flow mistakes - a token that is not invalidated, a redirect that is not validated, an error path that leaks information. Diagramming the flow makes these visible before they become bugs.

This guide walks through how to diagram common authentication flows: session-based login, token-based auth, and OAuth-style third-party login, with attention to the error and edge cases that matter most for security. A sequence diagram - showing the messages between the user, your application, and any identity provider over time - is usually the clearest format, and you can build one in the editor at /diagrams. The point is to reason about the design visually before committing it to code.

Choosing the right diagram type

Authentication involves several parties exchanging messages in a specific order, which is exactly what a sequence diagram is built to show. The vertical lifelines represent the participants - the user's browser, your server, a token store, an external provider - and the horizontal arrows represent the messages between them, read top to bottom in time. This makes the order of operations explicit, which matters enormously in auth, where doing things in the wrong order is often the vulnerability.

For the decision-heavy parts - is the password correct, is the token expired, did multi-factor succeed - a flowchart from /diagram-tools/flowchart-maker complements the sequence diagram, making the branches explicit. Many teams use both: a sequence diagram for the message exchange and a flowchart for the decision logic within it. The combination captures both the "who talks to whom, in what order" and the "what happens when a check fails" that together define a secure flow.

Sessions versus tokens

The two dominant models are worth diagramming separately because their flows differ in ways that matter. In session-based auth, the server creates a session after login and stores it, handing the browser a session identifier in a cookie; every subsequent request carries that cookie, and the server looks up the session. Your diagram should show where the session is created, where it is stored, how it is looked up on each request, and - critically - where and how it is destroyed on logout and expiry.

In token-based auth, the server issues a signed token after login that the client sends on each request; the server validates the token's signature and claims without a central lookup. This shifts the hard problems: tokens are hard to revoke before expiry, so your diagram must show the refresh flow and how you handle a compromised or expired token. Drawing both models side by side clarifies the trade-off - sessions are easy to revoke but require server state; tokens are stateless but harder to revoke - which is exactly the kind of design decision a diagram makes concrete.

The paths you must not forget

The happy path - correct credentials, valid token, everything fine - is the easy part and rarely where security fails. The paths below are where the real risk lives, and every one of them belongs in your diagram.

• Wrong password: how many attempts before lockout, and does the error reveal whether the account exists.
• Expired session or token: how the user is prompted to re-authenticate without losing their place.
• Token refresh: how a new token is issued and how a stolen refresh token is contained.
• Logout: how the session or token is actually invalidated everywhere, not just cleared from the browser.
• Multi-factor challenge: what happens when the second factor fails, times out, or is unavailable.
• OAuth callback: how the redirect and state parameter are validated to prevent forged callbacks.
• Concurrent sessions: whether logging in on a new device affects existing sessions.
• Account recovery: how password reset ties back into the auth flow without becoming a bypass.

Diagramming an OAuth flow

Third-party login via OAuth is the flow most improved by diagramming, because it involves the most parties and the most opportunities to get the order wrong. A sequence diagram should show all the participants - the user, your application, and the identity provider - and the full round trip: your app redirects the user to the provider, the user authenticates there, the provider redirects back with an authorization code, your app exchanges that code for tokens on the back channel, and only then is the user logged in. Drawing this makes it obvious why the code exchange happens server-side and why the state parameter exists.

The security-critical details show up clearly once drawn. The redirect back to your app must be to a pre-registered URL, the state parameter must be validated to prevent cross-site request forgery, and the token exchange must happen server-to-server so the client never sees the client secret. A diagram that shows these steps explicitly makes it hard to skip them, which is the whole value. Build the flow in Atlas Diagram Studio at /diagrams, share it for review with real-time collaboration so security-minded colleagues can annotate it, and keep it as documentation. The broader guide on documenting software with diagrams covers how such flows fit into a lasting documentation set.