ADR-0018: Optional Email + Password Login¶
Status: Accepted
Date: 2026-10-07
Deciders: nguyenhuuca
Related: ADR-0016 User Settings (passwordEnabled capability, R-1), PRD-user-notifications (email budget), PRD-password-login, plan-password-login
Context¶
Today users sign in only with a magic link (POST /user/join → email → GET /user/verify-magic). Users want the option to sign in with email + password (faster, works when email is slow or the daily email budget of 200 is exhausted).
Current code (verified 2026-10-07):
| Fact | Where | Consequence |
|---|---|---|
Auth mode is a global switch app.use-password-less: true (binds to AppProperties.usePasswordless via relaxed binding) |
application.yaml:113, UserController.signIn |
Either all users use magic links or all use passwords — not an option per user |
Legacy password path UserServiceImpl.joinSystem(LoginDto): unknown email → auto-registers with the supplied password, no email verification |
UserServiceImpl:95-119, 228-232 |
Account pre-hijacking: an attacker registers victim@x.com with their own password; when the victim later signs in by magic link they land in the same account, and the attacker keeps password access |
users.password nullable, BCrypt bean exists; loadUserByUsername rejects null passwords |
User, UserServiceImpl:122-128 |
Storage + hashing ready |
passwordEnabled in JWT//user/me/settings = !usePasswordless (global) |
UserServiceImpl.getToken, UserSettingsServiceImpl |
Settings UI already switches "Change password" vs "Magic link" on this flag |
MFA (TOTP) flow returns MFA_REQUIRED + session token, shared by both login paths |
UserServiceImpl, MFASessionStore |
Reusable as-is |
Brute-force protection = @RateLimited sliding window per IP only; no per-account lockout |
RateLimitAspect |
Distributed guessing against one account is unbounded |
JWTs are stateless, TTL from app.token-expired; no revocation |
JwtProvider |
A password change cannot log out other sessions today |
| No set/change/reset password endpoints | — | All new |
LoginDto.password is @Sensitive; logging.masking.fields includes password |
LoginDto, application.yaml:145 |
Audit logs already mask passwords |
Decision Drivers¶
- Email ownership must be proven before a password can exist (prevents pre-hijacking).
- Password is optional per user; magic link keeps working for everyone.
- Resist online guessing (per-account + per-IP), no user enumeration.
- A password change must be able to revoke other sessions.
- Golden Path only: Spring Security + BCrypt + JWT, Liquibase, Guava cache; no new infra.
Options¶
A. How does a password come into existence?¶
| Option | Description | Verdict |
|---|---|---|
A1. Sign up with email + password (legacy joinSystem) |
Unknown email + password → account created immediately | ❌ Pre-hijacking; unverified emails; spam accounts |
| A2. Sign up with email + password + email verification before activation | Account pending until link clicked | Adds a new pending state + verification email per signup (email budget) — more code, same email cost as magic link |
| A3. Set password after a magic-link sign-in (Settings → Sign-in) | First login is always by magic link (proves email); then user may add a password | ✅ Chosen — zero new trust paths; reuses existing verification; simplest |
B. Login endpoint¶
| Option | Verdict |
|---|---|
B1. Reuse POST /user/join with optional password field |
❌ Mixes "send me a link" and "check my password" semantics, error shapes and rate limits |
B2. New POST /user/login {email, password} |
✅ Clear contract; own rate limit and lockout; /user/join stays magic-link only |
C. Brute force¶
| Option | Verdict |
|---|---|
| C1. IP rate limit only (today) | ❌ Distributed attacks unbounded |
| C2. IP rate limit + per-account lockout (5 consecutive failures → locked 15 min; counter in DB) + generic error | ✅ Chosen. Lockout is time-boxed so it cannot be abused for permanent DoS; magic link still works while locked |
| C3. CAPTCHA | Deferred — new third-party dependency |
D. Revoking sessions on password change¶
| Option | Verdict |
|---|---|
| D1. Do nothing (stateless JWT) | ❌ Stolen token survives a password change |
D2. credentials_version on users, copied into JWT claim cv; JWTAuthenticationFilter rejects tokens whose cv ≠ current (Guava cache, 60 s TTL, evicted on change) |
✅ Chosen. One cached lookup per request; revocation within ≤ 60 s on other instances, immediate locally |
| D3. Server-side session store / token blacklist | Heavier; not needed |
E. Password policy¶
NIST SP 800-63B style: min 10 characters, max 72 bytes (BCrypt limit), any characters, must not contain the email local part, rejected if in a bundled list of the 10k most common passwords. No composition rules, no periodic expiry. BCrypt cost 12.
Decision¶
- Per-user password, opt-in, set only after a magic-link (or existing) authenticated session. Remove the global either/or switch: replace
app.use-password-lesswithapp.auth.password-login-enabled(defaulttrue) — a kill switch for the password endpoints only; magic link is always on. - Retire the legacy auto-register path (
UserController.signIn→joinSystem).POST /user/joinonly sends magic links. -
New endpoints
POST /user/login {email, password} → UserInfoDto | MFA_REQUIRED (public, @RateLimited 10/min/IP) PUT /user/password {currentPassword?, newPassword, otp?} → {jwt} (auth) DELETE /user/password {currentPassword, otp?} → {jwt} (fresh token; removal also bumps credentials_version) (auth)PUTfirst-time set: nocurrentPassword; requiresotpif MFA enabled.PUTchange: requirescurrentPassword(andotpif MFA).DELETE: back to magic-link-only.- Every set/change/delete: bump
credentials_version, return a fresh JWT for the current session, send a plain-text security email ("Mật khẩu của bạn vừa được thay đổi…"). - Login semantics
- Unknown email, no password set, wrong password, deactivated, locked → same
401 {"message":"INVALID_CREDENTIALS"}(no enumeration). Locked additionally logs server-side. - Spring
DaoAuthenticationProvider(already performs a dummy BCrypt check for unknown users → similar timing). - Success: reset counter; MFA → existing
MFA_REQUIREDflow. - Failure:
failed_login_count++; at 5 →locked_until = now + 15 min, counter reset. passwordEnabledin JWT //user/me/ settings becomes per user:password-login-enabled && user.password != null. New capabilitypasswordLoginAvailable= the global flag (FE shows the password tab).- Forgot password = request a magic link ("Quên mật khẩu? Gửi link đăng nhập"), then set a new password in Settings. No separate reset token flow.
Data Model¶
ALTER TABLE users
ADD COLUMN password_set_at TIMESTAMPTZ,
ADD COLUMN failed_login_count INT NOT NULL DEFAULT 0,
ADD COLUMN locked_until TIMESTAMPTZ,
ADD COLUMN credentials_version INT NOT NULL DEFAULT 0;
Existing rows: no account has a password (confirmed by the owner on prod, 2026-10-07) — schema-only migration, no data migration or backfill. Existing JWTs carry no cv claim and are treated as cv = 0 (the column default), so nobody is logged out by the deploy.
Security Notes¶
| Threat | Mitigation |
|---|---|
| Account pre-hijacking (CWE-287) | No password signup; password only from an authenticated session |
| Online guessing (CWE-307) | 10/min/IP + 5 failures → 15 min lock per account |
| User enumeration (CWE-204) | Single generic error for all failure causes; same status & shape |
| Credential storage (CWE-916) | BCrypt cost 12; 72-byte cap enforced (no silent truncation) |
| Session persistence after change (CWE-613) | credentials_version claim check |
| Password in logs (CWE-532) | @Sensitive on all password DTO fields; masking list already contains password |
| Stolen session sets a password | PUT change requires current password; MFA users also need OTP; security email notifies the owner |
Consequences¶
Positive
- Users get a fast login option without weakening email-verified identity.
- Email budget pressure drops (fewer magic links).
- Fixes the latent pre-hijacking hole by removing the auto-register path.
Negative
- Users must sign in by magic link once before they can use a password.
- One extra cached lookup per authenticated request (
credentials_version). - Lockout can be triggered by a third party for 15 min (magic link remains available).
Follow-ups
- CAPTCHA after N failures if abuse appears.
- Breached-password check (HIBP k-anonymity) — needs outbound call; deferred.
- Passkeys/WebAuthn as a later option.