d91aa83665
Organize documentation by moving requirements (HighLevelReqs, Component-*, lmxproxy_protocol) to docs/requirements/ and test infrastructure docs to docs/test_infra/. Updates all cross-references in README, CLAUDE.md, infra/README, component docs, and 23 plan files.
52 lines
3.5 KiB
Markdown
52 lines
3.5 KiB
Markdown
# Security & Auth Refinement — Design
|
|
|
|
**Date**: 2026-03-16
|
|
**Component**: Security & Auth (`docs/requirements/Component-Security.md`)
|
|
**Status**: Approved
|
|
|
|
## Problem
|
|
|
|
The Security & Auth doc defined roles and LDAP mapping but lacked specification for the authentication mechanism (previously stated Kerberos/NTLM, changed to direct LDAP bind), session management, token format, idle timeout, LDAP failure handling, and load balancer compatibility.
|
|
|
|
## Decisions
|
|
|
|
### Authentication Mechanism
|
|
- **Direct LDAP bind** with username/password. No Windows Integrated Authentication (Kerberos/NTLM).
|
|
- User provides credentials in a login form. App validates against LDAP/AD and retrieves group memberships.
|
|
- No local credential store or caching.
|
|
|
|
### Session Management — JWT
|
|
- **JWT with shared symmetric signing key** (HMAC-SHA256). Both central nodes use the same key from configuration.
|
|
- **Claims**: user display name, username, roles, permitted site IDs (for site-scoped Deployment). All authorization from token claims — no per-request database lookup.
|
|
- **Load balancer compatible** — no server-side session state, no sticky sessions needed.
|
|
|
|
### Token Lifecycle
|
|
- **15-minute JWT expiry with sliding refresh**. On refresh, app re-queries LDAP for current group memberships and reissues token with updated claims. Roles never more than 15 minutes stale.
|
|
- **30-minute idle timeout** (configurable). If no requests within the idle window, user must re-login.
|
|
- Active users stay logged in indefinitely via sliding refresh.
|
|
|
|
### LDAP Failure Handling
|
|
- **Fail closed for new logins** — can't authenticate without LDAP.
|
|
- **Grace period for active sessions** — valid JWTs continue to work with current roles. Token refresh skipped until LDAP recovers. Avoids disrupting active work during brief outages.
|
|
|
|
### Signing Key
|
|
- **Shared symmetric key** (HMAC-SHA256) in configuration. Both nodes are trusted issuers. Asymmetric keys rejected as unnecessary complexity for a two-node trusted cluster.
|
|
|
|
## Affected Documents
|
|
|
|
| Document | Change |
|
|
|----------|--------|
|
|
| `docs/requirements/Component-Security.md` | Replaced Windows Integrated Auth with direct LDAP bind. Added Session Management, Token Lifecycle, Load Balancer Compatibility, and LDAP Connection Failure sections. |
|
|
| `docs/requirements/HighLevelReqs.md` | Updated authentication description (Section 9.1) to reflect username/password with JWT. |
|
|
|
|
## Alternatives Considered
|
|
|
|
- **Windows Integrated Authentication (Kerberos/NTLM)**: Rejected by user — app authenticates directly against LDAP/AD.
|
|
- **Server-side sessions with cookie**: Rejected — doesn't work with load balancer without sticky sessions or shared session store.
|
|
- **Asymmetric JWT signing (RSA/ECDSA)**: Rejected — both nodes are trusted issuers, no third-party validation needed.
|
|
- **Two-token pattern (access + refresh)**: Rejected — sliding single JWT with short expiry is simpler and achieves the same goal.
|
|
- **No idle timeout (rely on JWT expiry)**: Rejected — user wanted explicit idle timeout separate from token refresh cycle.
|
|
- **Fail closed for active sessions on LDAP outage**: Rejected — would disrupt engineers mid-deployment during brief LDAP outages.
|
|
- **Credentials cached for LDAP outage resilience**: Rejected — adds local credential store complexity; correct behavior is to deny new logins when identity can't be verified.
|
|
- **Per-request role lookup from database**: Rejected — unnecessary DB query on every request when roles refresh every 15 minutes via LDAP.
|