Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Authentication: passwords, MFA & identity providers

Proving who is calling: why passwords are stored with a slow, salted key-derivation function, why a leaked hash table and a stuffed login form are different attacks, what a second factor stops and what it does not, and why one identity provider speaking OpenID Connect issues the proof the other apps trust.

A login log that reads like a crowd

A city library runs three web apps for its patrons: the catalogue, e-book lending and study-room booking. Each grew its own sign-in page and its own table of accounts. One night the catalogue's login log fills with lines like these:

  • 02:14:07 · ana.k@… · 401 · wrong password
  • 02:14:07 · t.oyelaran@… · 401 · no such account
  • 02:14:08 · m.ruiz@… · 200 · signed in

In one hour there are 40,000 attempts from about 3,000 addresses, almost every email tried once. 900 succeed at the first try, each one opening a patron's home address and reading history. The passwords were correct: patrons had reused them on a site breached years ago, and someone is replaying that site's list here. This is credential stuffing.

Authentication is the step where a caller proves who it is: it claims an identity and presents something only the real owner should have: a password, a code from a phone, a key on a device. If the check holds, the system records the result as a session or a token so the next request need not ask again; keeping, expiring and revoking that record are taken up in Sessions vs tokens: JWT, refresh & revocation. What the caller may then do is a separate question, for Authorization: roles, relationships & policies. A correct password proves only that the caller knows it, and last night 900 strangers did.

First question: could the table leak too?

The morning review checks the stored passwords first, since a leaked table would expose every account. The e-book app stores SHA-256(password) with no salt, which fails twice. SHA-256 is designed to be cheap, so one graphics card computes billions a second, and an attacker holding the table guesses offline, where no login limit applies. And with no salt, every patron who chose library2024 has the same hash, so one guess tests them all, and precomputed tables reverse common ones by lookup.

Passwords belong in a key-derivation function (KDF) built for them: Argon2id, scrypt, bcrypt or PBKDF2. Each password gets its own random salt, stored with the hash, so equal passwords hash differently and each account must be attacked separately. The function is deliberately slow, at a cost you choose: tuned so one check takes the server tens of milliseconds, it brings each of the attacker's graphics cards from billions of guesses a second to at most hundreds of thousands, far fewer with bcrypt or Argon2id. Argon2id and scrypt also demand memory per guess, which blunts parallel hardware. Salt and cost are usually recorded in the stored string, so the cost can be raised later; the old SHA-256 hashes can be wrapped at once, Argon2id over each, marked so the login applies both until the patron's next sign-in rehashes the password directly.

None of this would have stopped last night. A slow, salted KDF protects a table that leaks; the stuffing came through the login form with the right passwords.

What the login form gives away

Read the log again: if the form answers the way the log does, no such account versus wrong password tells anyone with a list which emails have accounts here. The form should give one answer, "wrong email or password", and take the same time for both, so the login runs the KDF against a dummy hash when the account does not exist.

Throttling helps less than it seems: a limit per address barely touches 3,000 addresses making about 13 attempts each, a limit per account never fires on an account tried once, and hard lockouts let attackers lock patrons out. What works better is watching the failure rate of the endpoint as a whole, challenging the traffic behind a spike, and refusing passwords already known from breaches when they are set, with a forced reset where one is already in use. How limits are counted and enforced is in Rate limiting.

Something a list cannot carry

The lasting answer is to stop accepting a password on its own. Multi-factor authentication (MFA) asks for a second proof of another kind: something the patron has, such as a phone or a security key, or something they are, such as a fingerprint read by their device. A stuffing list carries passwords, not phones.

The common second factor is a time-based one-time password (TOTP), the six-digit code of an authenticator app. At enrolment the server and the app share a random secret, usually through a QR code; afterwards both compute the code from that secret and the current 30-second window, and the server usually accepts the neighbouring window for clocks that drift, while it caps wrong attempts and refuses a code already accepted. The server must use that secret, so it is stored encrypted rather than hashed, under a key handled as Secrets management & encryption describes.

  • Codes by SMS are the weakest common factor: a number can be moved to an attacker's SIM through the carrier, and messages can be intercepted. Keep it as a fallback at most: while it is offered, an attacker can pick it.
  • Codes can be phished. A fake sign-in page that relays both to the real site within the window gets in: a code works wherever it is typed.
  • Passkeys and security keys (WebAuthn) close that gap. The device signs a fresh challenge with a private key bound to the site's domain, which the browser will not use on any other, so a look-alike domain gets nothing to replay. The server keeps only public keys, and a leaked table of them signs nobody in.

Recovery is authentication too: if "lost my phone" sends a link to an email account that the same reused password opens, the second factor protects nothing. Recovery links should expire soon, work once, and ask for any factor the patron still has.

Three login pages, one place to prove it

The review's real finding is structural: three apps, three ways of proving identity, MFA to build three times. So the library moves it all into one identity provider (IdP), a sign-in service that holds the accounts, hashes and factors and runs the login, and the apps stop touching passwords. An app sends a patron who is not signed in to the provider, which authenticates them, MFA included, and sends the browser back with an authorization code that the app exchanges, directly with the provider, for a signed statement: patron 18342, signed in at 09:40 with a password and a TOTP code, for the e-book app, valid for five minutes. One table to protect, one endpoint to watch, and since the provider remembers the sign-in, one login reaches all three apps.

One sign-in service, three apps

Only the sign-in service sees a password or a TOTP code. Each app receives a signed ID token instead.

The statement follows a standard. OpenID Connect (OIDC) is the identity layer on top of OAuth 2.0, which on its own lets an app obtain access to an API on a user's behalf; OIDC adds the ID token, a signed JSON Web Token saying who signed in and for which app, often with when and how they authenticated. It is meant for that app; a call to an API carries an access token issued for that API. Plain OAuth 2.0 delegates access, not authentication. The redirects and that code exchange, the authorization-code flow with its PKCE check, are taught step by step in OAuth 2.0 & OpenID Connect flows and drawn in the OAuth Authorization Code Flow Challenge, and Federated Identity shows the same trust extended to a provider someone else runs.

The app trusts the token only after checking its signature, issuer, audience and expiry, a check Sessions vs tokens: JWT, refresh & revocation walks through. A gateway can run the same check on access tokens once at the edge (API gateway & the edge), but a verified identity is not a permission: each service still decides, on the server, what patron 18342 may do.

Watch outValidate tokens at the edge and check authorization in the service. Never trust the client to enforce permissions, and never treat a valid login as blanket permission.

The price is that the provider sits on every sign-in: while it is down nobody can log in, though patrons already signed in can keep working until what their apps hold expires. Services calling each other do not sign in through it like a patron: they prove who they are with workload identities and mutual TLS, which Secrets management & encryption describes, or with tokens a provider issues to the service itself.

Where the password may go

In SSO Identity Provider, one self-hosted provider signs employees in through OIDC and enforces MFA with an authenticator app and an SMS fallback. The test of your Grid is a single property: only the provider ever receives a password, and every app receives tokens. Login Sequence draws the same login as numbered messages; put the hash comparison in the auth service, with one answer for a wrong password and an unknown account.

Practice this