# Decisions — August 21, 2026 One item, and it is the largest single change to the auth model since the login portal shipped. Like the August 18 and August 20 sets it is a **new item** with its own `D` id, not a reinterpretation of an existing one. `D1`–`D12` are taken; this is `D13`. Raised by Cody Schaefer on Aug 21 2026 while asking how the suite handles HTTPS. Nothing in `IMPLEMENTATION.md`, in `CR`/`F`/`S`/`A`/`B`/`C`, or in `docs/waves/backlog.md` covers authentication against the domain — so this is new scope, and it gets a new ID rather than being folded into the login-portal work that produced `server/auth.py`. --- ## D13 — Authentication moves to the domain over LDAPS - **Amends:** the authentication model shipped in `DEPLOY-login-portal.md` (bcrypt hashes in `users.password_hash`, verified in-process). That document describes what is being replaced, not what is wrong — it was correct for a suite with no directory behind it. - **Surface:** `server/` (`auth.py`, `app.py`, `models.py`, `manage_users.py`, `notify.py`, a new `ldap_auth.py`, a new migration), `html/` (`login.html`, `login.js`, `admin.js`, `users.js`), `requirements.txt`, `docker-compose.yml`, `Dockerfile`, deployment docs. - **Wave:** 10 (`docs/waves/wave-10.md`). Depends on wave 9 merged, which it is. ### The decision The suite stops storing passwords. A sign-in becomes a **simple bind to `ldaps://prime.local:636`** as `@prime.local` using the password the person typed. A successful bind is the authentication. `users.password_hash` is dropped from the schema. Four parts, all four required for the item to be done: 1. **LDAPS bind replaces local password verification.** `password_hash` is removed from the model and from the database by migration. No password is stored, hashed or otherwise. 2. **Accounts are provisioned just-in-time.** A successful bind for a username with no `users` row creates one, at the default role, with `full_name`/`email` read from the directory. 3. **A required group gates login.** An AD group is configured; a bind that succeeds but whose account is not in that group is refused. Membership is evaluated including nested groups. 4. **Existing accounts keep their roles, and roles stay local.** An existing `admin` stays an admin on first directory login. Granting admin to an existing account continues to work from the Admin console. The directory supplies *identity*; this app supplies *authorization*. ### Why LDAPS and not the certificate already in play Recorded because the question was asked directly and the answer is not obvious. The site's serving certificate is a **Let's Encrypt** cert (`CN=wp.controls.dev`, issued by `Let's Encrypt YE2`, expiring 2026-11-08) held by an **OpenResty** instance at `192.168.3.56` that is not part of this repo. It is a public domain-validated certificate. It attests that whoever presented it controls DNS for `wp.controls.dev`; it carries no user identity and no relationship to `prime.local`. There is no configuration that turns it into a domain credential, so cert-based auth was never available "for free". Client-certificate auth (mTLS) was considered and rejected for this wave: TLS terminates two hops upstream at OpenResty, so the API never sees the handshake, and doing it in-app would mean bypassing the proxy and losing the CSP/HSTS headers and static serving with it. ### What was verified before writing this (Aug 21 2026) | Fact | Value | |---|---| | LDAPS reachable | `192.168.3.37:636` open, TLS 1.3, `TLS_AES_256_GCM_SHA384` | | DC cert issuer | `CN=PRIME CONTROLS ISSUING CA 1, DC=prime, DC=local` | | Root of that chain | `CN=PRIME CONTROLS ROOT CA` (self-signed, expires 2051-09-09) | | Issuing CA expiry | 2036-09-09 | | DC cert SAN | `DR-DC10Core.prime.local`, `prime.local`, `PRIME` | | DCs published in `_ldap._tcp.prime.local` | six — `nla-dc10`, `lew-dc20`, `dr-dc30-core`, `lew-dc40`, `SABINEDC`, `dr-dc10core` | | Chain validates against root+issuing bundle | yes — `Verify return code: 0 (ok)` | Two consequences of that table, both binding on the build: - **Connect to `prime.local`, not to a DC name or an IP.** Every DC's certificate carries `prime.local` in its SAN, so the domain name both passes hostname validation and round-robins across all six DCs. Verified: `prime.local` gives `0 (ok)`; the raw IP `192.168.3.37` gives `62 (hostname mismatch)`, because there is no IP SAN. - **The trust anchor is a CA certificate, not a certificate issued to this app.** The API is the TLS *client*; clients present nothing. It needs `PRIME CONTROLS ROOT CA` plus `PRIME CONTROLS ISSUING CA 1` as a PEM bundle, which is public information. No CSR, no enrollment, no private key, nothing to request from IT. ### Non-negotiables These are the ways this change goes wrong, and each has a done-when check in wave 10. - **An empty password must be rejected before `bind()` is called.** In LDAP a simple bind with an empty password is an *anonymous* bind and it **succeeds**. Without an explicit guard, a blank password authenticates as any username submitted. This is the single highest-severity failure mode in the item and it gets its own test. - **`validate=ssl.CERT_REQUIRED` with an explicit CA file.** Not `CERT_NONE`, and not the system trust store. `CERT_NONE` still encrypts, so it fails silently — what it loses is the ability to distinguish the real DC from an attacker who terminates the TLS session, harvests the domain password and relays the bind onward. Since domain credentials now cross that channel, a compromise escalates from "this app" to Windows, mail and file shares. The system store is refused separately because it currently trusts five other self-signed CAs (`prime-DR-CAPRIME-CA`, `prime-DR-CA_PRIME-CA`, `prime-DR-DC20-CA`, `PRIME CONTROLS ISSUING CA 2`, and a stray `L55401TDKLY3.prime.local` machine cert in Trusted Root). - **The app's lockout must trip below the domain's.** `LOGIN_MAX_ATTEMPTS` currently writes to the local `users` row. Once failures are binds, they count against the **AD** lockout policy, so an unauthenticated caller hammering `/api/auth/login` can lock real domain accounts out of Windows. The local throttle must stop calling the DC before the domain threshold is reached. - **Never leak which usernames exist.** `login()` today equalises response timing on purpose so a caller cannot enumerate accounts. Directory error 49 sub-codes (`52e` bad password, `532` password expired, `533` disabled, `775` locked) are useful in the log and must not reach the response body. ### Answered August 21, 2026 — both were raised as open and both were decided **Break-glass: none. LDAPS is the only way in.** Asked and reaffirmed after the lockout risk was stated. There is no emergency local account, no env-var bypass, and no CLI-minted session. The consequence is explicit and belongs in the runbook rather than being discovered: **if the domain is unreachable, or `LDAP_CA_FILE` is wrong, or the required group is misconfigured, nobody can sign in — including admins — and no amount of shell access fixes it except correcting the configuration and restarting.** `T10.5`'s validate-on-save guard is therefore not a nicety; with no fallback it is the only thing standing between a typo in the group field and a total outage. Three things follow, and they are done-when checks in wave 10 rather than advice: - The startup log must state whether LDAP is configured and reachable, so a broken deploy is visible in `docker compose logs api` and not only at the login box. - `/api/health` stays exempt from auth (it already is) so the outage is diagnosable. - The group setting cannot be saved without proving the saving admin is a member. **Identity: bind on `sAMAccountName`, match on `sAMAccountName` *or* `mail`.** A simple bind can only carry one identifier, and AD accepts the UPN form — so the bind is `sAMAccountName@prime.local` and that is what the login box takes. Matching an existing local row is a separate question, and it uses **both**: after a successful bind the directory's `sAMAccountName` and `mail` are both read, and `auth.find_user` is extended to match a local row on either, case-insensitively. That is what keeps an existing admin's role whether their hand-typed username was `c.schaefer` or `c.schaefer@prime-controls.com`. Two consequences worth knowing: - The mail domain (`prime-controls.com`) is not the AD domain (`prime.local`), so `mail` is never a valid bind string. It is a matching key only. - If someone types an address at the login box, the local part is used as the `sAMAccountName` — **one** bind attempt, never several, because each failed bind counts against the domain lockout policy. That assumes the mail local part equals the `sAMAccountName`. Where it does not, the person must type their short logon name; this is logged when it happens and documented in `T10.8`. - The production `users` table should still be compared against AD before this deploys. A row matching on neither key gets a *second*, JIT-provisioned account at the default role rather than keeping its admin. Matching on two keys narrows that risk; it does not remove it. ### Explicitly out of scope - mTLS / client-certificate authentication (see above). - Kerberos / SPNEGO single sign-on. It is the better long-term answer for domain-joined desktops and needs a keytab, an SPN and browser trust configuration; it is not this item. - Group-to-role mapping (e.g. an AD group that confers `project_admin`). Criterion 4 keeps authorization local on purpose. Worth its own item later; logged in `backlog.md`. - Replacing the Let's Encrypt certificate or changing anything on the OpenResty host. --- ## D14 — The CLI authenticates against the domain, and stops creating accounts - **Amends:** `D13` criterion 4, which said role granting keeps working *from the Admin console*. It said nothing about `manage_users.py`, which had no authentication of any kind. Requiring one is a new requirement, so it gets its own id rather than widening criterion 4. - **Surface:** `server/manage_users.py` - **Task:** `T10.9` ### The decision 1. **`create-admin` and `create` are removed.** `D13` provisions accounts on first successful sign-in, so creating them by hand is redundant. Removing them also closes a class of problem: every row now originates from a bind, so a username cannot be typed in wrong and end up orphaned from the directory identity it was meant to match. That risk now applies only to rows the old CLI already created. 2. **`promote` and `demote` replace them.** The directory supplies identity; this app supplies authorization, and this is where authorization is assigned from a shell. 3. **Every state-changing command requires a domain bind.** Prompted, via `getpass`. There is deliberately no `--password` flag: that would put a live domain password into shell history and into `ps` output for every other user on the box. 4. **`list` needs no credential**, so an outage stays diagnosable. ### Bootstrapping the first admin, which changed shape Two steps, in order: **sign in once** (which provisions the account at `project_user`), then **`promote `**. Before D14 the first admin was created with a password; there is no password now, and no account to create. ### What this is worth, stated plainly Anyone with a shell on the api container can still write to the `users` table directly with `psql` or `sqlite3`. So the bind is **defence in depth and, mostly, ACCOUNTABILITY** — not a security boundary. Before D14 every role change made from a shell was invisible in `AuditLog` while the same change through the console was recorded; now both are recorded and both name a person. Any-domain-user was accepted as sufficient (no privileged group exists on this estate, and machine access is already restricted to a few people), which was decided knowing the above. ### Two deliberate divergences from the API - **The bind does NOT apply the login group gate.** If a mistyped required group locks everyone out of the console, this tool has to still work — otherwise the only route to fixing the lockout is the thing the lockout prevents. - **Changing your OWN role is permitted here.** `set_user_role` in `app.py` forbids it to stop an admin locking themselves out of the console. Here it is the entire bootstrap path, so it is allowed and recorded with `{"self": true}` in the audit detail. The last-admin guard is kept, matching `set_user_role`: an app with no admin cannot be administered, and there is no password login left to recover through.