Cheat sheet · Security
Authentication
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
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_apiMermaid: 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 UnauthorizedD2
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
@endumlPlantUML: 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
@endumlRecap
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
| Metric | Start | End |
|---|---|---|
| Leaked hashes cracked | 62% | 0.5% |
| Login time | 40 ms | 290 ms |
| Account takeovers | 35/day | 0/day |
Steps
- Problem The users table leaks
A backup of the users table ends up public.
- 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.
- 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. - Problem Every service asks the session store
An orders service appears.
- 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.
- Problem A stolen token lives for 30 days
A token leaked through a logged URL.
- Fix Short access token plus a refresh token
Access tokens now live 15 minutes.
- Fix Revocation: logout that really logs out
On logout or password change the API deletes the user's refresh token family.
- Fix Login through an identity provider
Users can now sign in with a company account.
- Fix A second factor stops reused passwords
Attackers try email and password pairs leaked from other sites against
/login. - 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.