75 lines
2.6 KiB
Markdown
75 lines
2.6 KiB
Markdown
# ADR-004: Authentication Strategy
|
|
|
|
## Status
|
|
Accepted
|
|
|
|
## Context
|
|
The platform needs secure authentication for both technical and non-technical users. Requirements include: primary passkey support, password fallback, session management, and resistance to common attacks (phishing, credential stuffing, session hijacking).
|
|
|
|
## Decision
|
|
**Passkeys as primary authentication method, Argon2id-hashed passwords as fallback.**
|
|
|
|
### Implementation
|
|
|
|
1. **Registration Flow**:
|
|
- User provides email
|
|
- System generates WebAuthn registration challenge
|
|
- Browser creates passkey ( Touch ID, Windows Hello, YubiKey)
|
|
- Server stores credential ID and public key
|
|
- Optional: user sets password fallback
|
|
|
|
2. **Login Flow (Passkey)**:
|
|
- User enters email
|
|
- Server returns WebAuthn assertion challenge
|
|
- Browser signs challenge with passkey
|
|
- Server verifies signature, creates session
|
|
|
|
3. **Login Flow (Password)**:
|
|
- User enters email + password
|
|
- Server verifies Argon2id hash (constant-time comparison)
|
|
- If valid, creates session
|
|
- Prompts to set up passkey (progressive enhancement)
|
|
|
|
4. **Session Management**:
|
|
- Signed cookies with 24-hour expiry
|
|
- Refresh tokens rotate on each use
|
|
- Sessions stored in database (revocable)
|
|
- HttpOnly, Secure, SameSite=Strict flags
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- Passkeys are phishing-resistant by design
|
|
- No password database to breach (if passkey-only)
|
|
- Argon2id is winner of Password Hashing Competition
|
|
- Session tokens are revocable server-side
|
|
- Progressive enhancement: passkey users never type passwords
|
|
|
|
### Negative
|
|
- Passkey support varies by browser/OS
|
|
- Users may lose access if they lose all devices (recovery flow needed)
|
|
- WebAuthn implementation complexity (mitigated by go-webauthn library)
|
|
- Backup codes or recovery email needed for account recovery
|
|
|
|
## Alternatives Considered
|
|
|
|
### OAuth 2.0 / SSO Only
|
|
- **Pros**: No password management, familiar UX
|
|
- **Cons**: Vendor lock-in to identity providers, privacy concerns, not self-hosted
|
|
- **Rejected**: Violates "no vendor lock-in" principle
|
|
|
|
### Passwords Only (with 2FA)
|
|
- **Pros**: Simple, universally supported
|
|
- **Cons**: Vulnerable to phishing, credential stuffing, SIM swapping
|
|
- **Rejected**: Passkeys are strictly superior
|
|
|
|
### Magic Links
|
|
- **Pros**: No passwords, simple UX
|
|
- **Cons**: Email dependency, slower, inbox security issues
|
|
- **Rejected**: Less secure than passkeys, poor for frequent login
|
|
|
|
## References
|
|
- WebAuthn spec: https://www.w3.org/TR/webauthn-2/
|
|
- go-webauthn library: https://github.com/go-webauthn/webauthn
|
|
- Argon2id RFC: https://datatracker.ietf.org/doc/html/rfc9106
|