HLD ยท 5 min read

Design an Authentication System

Designing a scalable authentication and session management system.

On this page
  1. Functional requirements
  2. Password storage: hashing and salting
  3. JWT - JSON Web Token
  4. The refresh token pattern
  5. OTP - forgot password flow
  6. OAuth 2.0 - Login with Google
  7. The data layer
  8. Non-functional requirements
  9. Latency
  10. Scalability
  11. Security

Authentication is how your system verifies who a user is. Authorization is what they're allowed to do. This design covers the full authentication stack - registration, login, session management, token refresh, OTP, and OAuth... and how to build it securely at scale.

Functional requirements

  1. Register -> save credentials securely
  2. Login -> verify credentials, issue tokens
  3. Session mgmt -> keep user logged in via tokens
  4. Token refresh -> renew session without re-login
  5. Forgot passwd -> OTP verification, reset credentials
  6. Logout -> invalidate session

Password storage: hashing and salting

Passwords are never stored as plain text. If your DB is compromised and an attacker sees "password123" directly, yeah that's game over. The fix is hashing.

But hashing alone has a vulnerability. If two users share the same password, they produce the same hash. A hacker with a rainbow table (precomputed list of common password hashes) can instantly reverse engineer them.

Salting fixes this. A unique random string is generated per user and appended to the password before hashing:

text
password    = "password123"
salt        = "xK92p"   (unique per user, random)
stored_hash = bcrypt("password123" + "xK92p")

User 1: bcrypt("password123" + "xK92p") = "a3f9c2..."
User 2: bcrypt("password123" + "m7n1q") = "z8p4r1..."

Same password, completely different hashes. Rainbow tables useless. The salt is stored alongside the hash. It's not secret, it just makes every hash unique. Use bcrypt or Argon2. Both have salting built in and are intentionally slow to compute, making brute force attacks impractical.

In practice: because bcrypt and Argon2 have salting built in, they generate the salt for you and store it inside the hash string they return. You never append a salt yourself or keep it in a separate column; the example above just shows what happens under the hood.

JWT - JSON Web Token

After login, the server issues a JWT so the user doesn't send their password on every request. A JWT has three parts:

text
header.payload.signature

header    -> algorithm (HS256)
payload   -> { userID: "123", role: "admin", exp: 1714000000 }
signature -> HMAC-SHA256(header + "." + payload, secret_key)
             proves token hasn't been tampered with

JWT is stateless i.e. the server stores nothing. Every request carries the token, the server verifies the signature mathematically, and reads the payload. Zero DB lookup. Sub-millisecond verification on every request.

Worth knowing: the payload is only Base64-encoded, not encrypted. Anyone holding the token can read it, so never put secrets or sensitive personal data in it. The signature stops tampering, not reading.

The refresh token pattern

JWT has one weakness. Once issued, it's valid until expiry. A stolen token can't be invalidated. Short expiry (15 minutes) limits damage but logs users out constantly. The fix is two tokens:

text
Login -> issue two tokens:

  Access Token  -> JWT, expires in 15 minutes
                   stateless, verified by signature
                   NOT stored in DB

  Refresh Token -> opaque random string, 30 days
                   stored in DB + Redis cache

Every request uses Access Token (fast, no DB hit)

Access Token expires:
  -> client sends Refresh Token
  -> server validates against DB
  -> issues new Access Token

Logout:
  -> delete Refresh Token from DB
  -> stolen Access Token expires in max 15 min
  -> Refresh Token dead -> can't renew

Best of both worlds: short-lived access tokens for security, refresh tokens for good UX.

A common hardening step on top of this is refresh token rotation: every refresh also issues a new refresh token and retires the old one. If a retired token is ever presented again, someone has stolen it, so the server revokes the whole session.

OTP - forgot password flow

text
User enters email
  -> generate 6-digit OTP
  -> store hashed OTP in OTP table with 10 min TTL
  -> send via Notification Service (SMS or email)

User submits OTP:
  -> verify hash
  -> valid + not expired -> allow password reset
  -> invalid? -> increment attempts
              -> 3 failed attempts -> block, force resend

OTP is always stored hashed, never plain text. Attempt limiting prevents brute force (there are only 1M possible 6-digit OTPs). The OTP is sent through the Notification Service.

OAuth 2.0 - Login with Google

OAuth lets your app delegate authentication to a trusted provider - Google, GitHub, Apple. Four players: the user, your app, the Auth Server (Google), and the Resource Server (Google's API).

text
User clicks "Login with Google"
  -> your app redirects to Google Auth Server
  -> Google asks user for permission
  -> user approves
  -> Google issues Authorization Code to your app
  -> your app exchanges code + secret key for Access Token
  -> fetch user profile (name, email, picture)
  -> user is logged in

The Authorization Code step exists because the redirect happens in the browser, so it's visible to anyone. The code is useless without your app's secret key, so interception is harmless. OAuth handles the "who vouches for this user" question. JWT handles the token format. They work together.

Two details worth knowing:

  • Apps that can't keep a secret, like mobile apps and single-page web apps, have no secret key to protect the code. They use PKCE instead: the app sends a hashed one-time value when it starts the login and the original value when it exchanges the code, so an intercepted code is still useless.
  • Strictly, OAuth 2.0 is about authorization (granting access to an API). "Login with Google" uses OpenID Connect, a layer on top of OAuth that also returns an ID token saying who the user is.

The data layer

Three DB tables and one cache:

  • Users table (PostgreSQL) - userID, email, password_hash, salt, role, created_at. Queried only on registration and login. Never stores plain passwords or tokens.
  • Refresh Token table (PostgreSQL) - tokenID, userID, refresh_token_hash, expires_at, device_info, created_at. One row per active session. Deleted on logout.
  • OTP table (PostgreSQL) - otpID, userID, otp_hash, expires_at, attempts, created_at. Short-lived rows, auto-deleted after expiry.
  • Redis cache - refresh token lookups (faster than DB), user session data (role, email), failed login attempt counters for rate limiting.

Access Tokens are never stored anywhere. JWT is self-verifying. That's the point.

Non-functional requirements

Latency

JWT verification on every request is pure math. No DB, no cache, sub-millisecond. Refresh token lookups hit Redis first. Login is the only flow that touches PostgreSQL, and it happens rarely relative to request volume.

Scalability

Stateless JWT means any Auth Service instance can verify any token. No shared session state between servers. Scale horizontally with zero coordination overhead. Redis handles the small amount of shared state (refresh tokens, rate limiting counters).

Security

Passwords hashed with bcrypt + unique salt. Access Tokens short-lived (15 min). Refresh Tokens stored hashed in DB. OTPs hashed, time-limited, attempt-limited. Rate limiting on login attempts via Redis counters. OAuth delegates password responsibility to trusted providers entirely.