mufassall

Cheat sheet · Security

Authentication

14 min · Intermediate · mufassall.dtwin.uz/en/l/authentication/

← Open the lesson

The problem

How a service learns who is calling: storing passwords so a leak is not a disaster, sessions and tokens, how long a token lives and how to kill it, logging in through an identity provider, and a second factor.

What you learn

  • Why passwords are stored with a slow, salted hash like argon2 or bcrypt
  • Server sessions vs JWT access tokens, and when each fits
  • Short access tokens, refresh tokens and revocation
  • Login through an identity provider (OAuth2 / OIDC) and MFA
Final scene
55%25%

Diagram as code

The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.

Mermaid: flowchart

flowchart LR
  n_user(("User"))
  n_web(["Web app"])
  n_api["Auth API"]
  n_users[("Users DB")]
  n_sessions{{"Session store"}}
  n_orders["Orders service"]
  n_attacker(("Attacker"))
  n_idp>"Identity provider"]
  n_user --> n_web
  n_web --> n_api
  n_api --> n_users
  n_api --> n_sessions
  n_web --> n_orders
  n_web --> n_idp
  n_api --> n_idp
  n_attacker --x n_api

Mermaid: request sequence

sequenceDiagram
  actor n_attacker as Attacker
  participant n_users as Users DB
  participant n_api as Auth API
  participant n_web as Web app
  participant n_orders as Orders service
  participant n_sessions as Session store
  participant n_idp as Identity provider
  Note over n_attacker,n_users: The users table leaks
  n_attacker->>n_users: SELECT id, email, password_sha256 FROM users#59;
  n_users-->>n_attacker: 120000 rows, first one:
  Note over n_api,n_users: Store a slow, salted hash
  n_api->>n_users: SELECT id, password_hash FROM users
  n_users-->>n_api: 1 row
  Note over n_web,n_api: Session: a random id in a cookie
  n_web->>n_api: POST /login HTTP/1.1
  n_api-->>n_web: HTTP/1.1 200 OK
  Note over n_orders,n_sessions: Every service asks the session store
  n_orders->>n_sessions: GET sess:***
  n_sessions-->>n_orders: #34;u_42#34;
  Note over n_web,n_orders: JWT: a signed token any service can check
  n_web->>n_orders: GET /orders HTTP/1.1
  n_orders-->>n_web: HTTP/1.1 200 OK
  Note over n_attacker,n_orders: A stolen token lives for 30 days
  n_attacker->>n_orders: GET /orders HTTP/1.1
  n_orders-->>n_attacker: HTTP/1.1 200 OK
  Note over n_web,n_api: Short access token plus a refresh token
  n_web->>n_api: POST /token HTTP/1.1
  n_api-->>n_web: HTTP/1.1 200 OK
  Note over n_api,n_sessions: Revocation: logout that really logs out
  n_api->>n_sessions: DEL rt:u_42:fam_19
  n_sessions-->>n_api: (integer) 1
  Note over n_api,n_idp: Login through an identity provider
  n_api->>n_idp: POST /oauth2/token HTTP/1.1
  n_idp-->>n_api: HTTP/1.1 200 OK
  Note over n_attacker,n_api: A second factor stops reused passwords
  n_attacker->>n_api: POST /login HTTP/1.1
  n_api-->>n_attacker: HTTP/1.1 401 Unauthorized

D2

direction: right

n_user: "User" {
  shape: person
}
n_web: "Web app" {
  shape: rectangle
}
n_api: "Auth API" {
  shape: rectangle
}
n_users: "Users DB" {
  shape: cylinder
}
n_sessions: "Session store" {
  shape: hexagon
}
n_orders: "Orders service" {
  shape: rectangle
}
n_attacker: "Attacker" {
  shape: person
}
n_idp: "Identity provider" {
  shape: cloud
}

n_user -> n_web
n_web -> n_api
n_api -> n_users
n_api -> n_sessions
n_web -> n_orders
n_web -> n_idp
n_api -> n_idp
n_attacker -> n_api {
  target-arrowhead.shape: cross
}

PlantUML: request sequence

@startuml
actor "Attacker" as n_attacker
database "Users DB" as n_users
participant "Auth API" as n_api
participant "Web app" as n_web
participant "Orders service" as n_orders
collections "Session store" as n_sessions
boundary "Identity provider" as n_idp
note over n_attacker, n_users : The users table leaks
n_attacker -> n_users : SELECT id, email, password_sha256 FROM users;
n_users --> n_attacker : 120000 rows, first one:
note over n_api, n_users : Store a slow, salted hash
n_api -> n_users : SELECT id, password_hash FROM users
n_users --> n_api : 1 row
note over n_web, n_api : Session: a random id in a cookie
n_web -> n_api : POST /login HTTP/1.1
n_api --> n_web : HTTP/1.1 200 OK
note over n_orders, n_sessions : Every service asks the session store
n_orders -> n_sessions : GET sess:***
n_sessions --> n_orders : "u_42"
note over n_web, n_orders : JWT: a signed token any service can check
n_web -> n_orders : GET /orders HTTP/1.1
n_orders --> n_web : HTTP/1.1 200 OK
note over n_attacker, n_orders : A stolen token lives for 30 days
n_attacker -> n_orders : [duplicate] GET /orders HTTP/1.1
n_orders --> n_attacker : HTTP/1.1 200 OK
note over n_web, n_api : Short access token plus a refresh token
n_web -> n_api : POST /token HTTP/1.1
n_api --> n_web : HTTP/1.1 200 OK
note over n_api, n_sessions : Revocation: logout that really logs out
n_api -> n_sessions : DEL rt:u_42:fam_19
n_sessions --> n_api : (integer) 1
note over n_api, n_idp : Login through an identity provider
n_api -> n_idp : POST /oauth2/token HTTP/1.1
n_idp --> n_api : HTTP/1.1 200 OK
note over n_attacker, n_api : A second factor stops reused passwords
n_attacker -> n_api : POST /login HTTP/1.1
n_api --> n_attacker : HTTP/1.1 401 Unauthorized
@enduml

PlantUML: components

@startuml
left to right direction
actor "User" as n_user
agent "Web app" as n_web
component "Auth API" as n_api
database "Users DB" as n_users
stack "Session store" as n_sessions
component "Orders service" as n_orders
actor "Attacker" as n_attacker
cloud "Identity provider" as n_idp
n_user --> n_web
n_web --> n_api
n_api --> n_users
n_api --> n_sessions
n_web --> n_orders
n_web --> n_idp
n_api --> n_idp
n_attacker -[#c62828]-> n_api
@enduml

Recap

Four rules for authentication.

1) Store passwords with a slow, salted hash (argon2id, bcrypt). 2) Sessions are easy to revoke; JWTs are easy to verify anywhere, so keep them short. 3) Pair a 15-minute access token with a rotated refresh token, and revoke by deleting refresh tokens. 4) Prefer an identity provider for login and add MFA; never put tokens in URLs, where logs keep them.

Numbers: at the start and at the end

MetricStartEnd
Leaked hashes cracked62%0.5%
Login time40 ms290 ms
Account takeovers35/day0/day

Steps

  1. Problem The users table leaks

    A backup of the users table ends up public.

  2. Fix Store a slow, salted hash

    The API now stores passwords with argon2id (bcrypt works too): a random salt per user and a hash that costs about 250 ms and 64 MB to compute.

  3. Case Session: a random id in a cookie

    After the password checks out, the API creates a session in the store (u_42, expires in 7 days) and gives the browser a random id in a cookie.

  4. Problem Every service asks the session store

    An orders service appears.

  5. Fix JWT: a signed token any service can check

    The auth API now issues an access token: a JWT with the user id and an expiry, signed with the API's private key.

  6. Problem A stolen token lives for 30 days

    A token leaked through a logged URL.

  7. Fix Short access token plus a refresh token

    Access tokens now live 15 minutes.

  8. Fix Revocation: logout that really logs out

    On logout or password change the API deletes the user's refresh token family.

  9. Fix Login through an identity provider

    Users can now sign in with a company account.

  10. Fix A second factor stops reused passwords

    Attackers try email and password pairs leaked from other sites against /login.

  11. Recap Recap

    Four rules for authentication.

Terms

Password hashing (salted)
Store a slow hash (argon2id or bcrypt) with a random salt per user, never the password itself. Login gets slower by an unnoticeable amount, while cracking a leaked table becomes millions of times harder.
JWT
A signed token that any service can verify without a database lookup. It cannot be revoked instantly, so the access token is kept short-lived and paired with a refresh token.
OAuth2 / OIDC
The user logs in at an identity provider and comes back with a one-time code, which the API exchanges server-to-server for an id token. The app never sees the password.
Refresh token
A long-lived token used to get a new short-lived access token when the old one expires. It goes only to the auth server, is rotated on every use and can be revoked if stolen.