Docs: make the three account sources unmistakable (auth.users, local-users.json, auth.admins) #846

Closed
opened 2026-10-06 14:30:38 +00:00 by Cordy · 2 comments
Owner

Start after: #838 + #839 merge, so the docs describe the final revocation behaviour.

Problem

The docs don't make clear that Cairn has two kinds of local account plus a separate admin list. A careful reader (Nikola, 2026-10-06) took auth.users to mean "users from the IdP". That isn't what it is.

Source Where it lives Created and managed Password checked by Dashboard can delete, reset or demote
auth.users (config users) config.json / env Only by editing config and restarting Cairn (hash in config) No: break-glass
Local accounts local-users.json in state Users & access in the UI Cairn (argon2id in the state file) Yes
Directory users LDAP/AD or Keycloak In the directory The directory No (they are managed in the directory; Cairn only re-checks)
auth.admins config.json / env Config only n/a: it's a role list, not accounts No: the names listed are always admin

auth.admins can name an account of any of the three kinds. It guarantees the role, not the account. If a directory user listed there is deleted or disabled in the directory, that user is still signed out (behaviour from #838/#839).

To do

  • One "Account sources" section, probably in docs/handbook/local-accounts.md, with the table above and a worked config example (a break-glass user plus an AD user in auth.admins). Link to it from deployment.md, admin-policy.md and the LDAP and OIDC sections.
  • Explain break-glass: why auth.users exists, when to use it, and that the dashboard can't lock it out.
  • Check whether config users and auth.admins entries appear on Users & access, and how (badge or read-only). Document what the UI shows. If they don't appear, decide whether they should; that's a question for when this issue is worked on.
  • Initial admin from the first-run wizard: when an instance is deployed with nothing attached and the wizard asks for the initial local admin, check where that account lands (local-users.json vs config). Check whether it is protected like auth.users or can be deleted and demoted like any dashboard account, and whether that's a lockout risk (for example, the last admin deleting themselves). AdminCount exists; verify what guards it actually provides. Document the result, and file a separate issue if a gap shows up.
  • All four languages for any UI copy touched. No long dash.

Ask the open decisions when this is worked on.

**Start after:** #838 + #839 merge, so the docs describe the final revocation behaviour. ## Problem The docs don't make clear that Cairn has two kinds of local account plus a separate admin list. A careful reader (Nikola, 2026-10-06) took `auth.users` to mean "users from the IdP". That isn't what it is. | Source | Where it lives | Created and managed | Password checked by | Dashboard can delete, reset or demote | |---|---|---|---|---| | `auth.users` (config users) | `config.json` / env | Only by editing config and restarting | Cairn (hash in config) | **No**: break-glass | | Local accounts | `local-users.json` in state | Users & access in the UI | Cairn (argon2id in the state file) | Yes | | Directory users | LDAP/AD or Keycloak | In the directory | The directory | No (they are managed in the directory; Cairn only re-checks) | | `auth.admins` | `config.json` / env | Config only | n/a: it's a **role list**, not accounts | No: the names listed are always admin | `auth.admins` can name an account of any of the three kinds. It guarantees the role, not the account. If a directory user listed there is deleted or disabled in the directory, that user is still signed out (behaviour from #838/#839). ## To do - [ ] One "Account sources" section, probably in `docs/handbook/local-accounts.md`, with the table above and a worked config example (a break-glass user plus an AD user in `auth.admins`). Link to it from deployment.md, admin-policy.md and the LDAP and OIDC sections. - [ ] Explain break-glass: why `auth.users` exists, when to use it, and that the dashboard can't lock it out. - [ ] Check whether config users and `auth.admins` entries appear on Users & access, and how (badge or read-only). Document what the UI shows. If they don't appear, decide whether they should; that's a question for when this issue is worked on. - [ ] **Initial admin from the first-run wizard:** when an instance is deployed with nothing attached and the wizard asks for the initial local admin, check where that account lands (`local-users.json` vs config). Check whether it is protected like `auth.users` or can be deleted and demoted like any dashboard account, and whether that's a lockout risk (for example, the last admin deleting themselves). `AdminCount` exists; verify what guards it actually provides. Document the result, and file a separate issue if a gap shows up. - [ ] All four languages for any UI copy touched. No long dash. Ask the open decisions when this is worked on.
Author
Owner

Added to scope (Nikola, 2026-10-06): remove the long dashes (U+2014) from the Users & access copy, which breaks the no-long-dash rule for UI text. Seen on the dogfood:

  • "Local accounts live in local-users.json with argon2id password hashes — the file itself is readable…"
  • "Cairn only grants or removes its administrator role here — the accounts themselves are managed in the directory." (appears twice: the Directory accounts intro and the info box below the table)

While on this page, grep web/static/index.html for any other U+2014 in i18n strings, all four languages, and fix them in the same change.

Added to scope (Nikola, 2026-10-06): remove the long dashes (U+2014) from the Users & access copy, which breaks the no-long-dash rule for UI text. Seen on the dogfood: - "Local accounts live in local-users.json with argon2id password hashes — the file itself is readable…" - "Cairn only grants or removes its administrator role here — the accounts themselves are managed in the directory." (appears twice: the Directory accounts intro and the info box below the table) While on this page, grep `web/static/index.html` for any other U+2014 in i18n strings, all four languages, and fix them in the same change.
Author
Owner

Findings (2026-10-07)

  • Config users (auth.users) (internal/config LocalUser{username, passwordHash}) can sign in in every mode, but Users & access never lists them: localUserRows() only reads local-users.json. They don't count against the 50-account limit.
  • auth.admins names appear in the Directory accounts table as "via the configuration" (luViaConfig) once they've signed in.
  • The wizard admin (setup.go) is created in local-users.json with admin=true, so it's a normal dashboard account. Existing guards: you can't delete your own account (localUserDelete), and you can't remove or demote the last administrator (adminTotal() counts config admins, runtime directory admins and local admins). Since #852 setup never reopens after that.
  • Long dashes: about 158 literal "—" plus — escapes in web/static/index.html, a few in login.html, setup.html and storage-setup.html, and some in server error strings shown in the UI (e.g. the local-account name clash in localusers.go).
  • The empty-state text "Only your administrator account exists so far." is wrong on an IdP instance where no local admin exists (seen on cairn-enc).

Decisions (Nikola, 2026-10-07)

  1. Show config accounts read-only under Local accounts with a "Config file" badge and no actions. A mockup comes first.
  2. Wizard admin: keep it as a normal dashboard account, protected by the existing guards. Document it, and recommend an auth.users break-glass account for production.
## Findings (2026-10-07) - **Config users (`auth.users`)** (`internal/config` `LocalUser{username, passwordHash}`) can sign in in every mode, but Users & access never lists them: `localUserRows()` only reads `local-users.json`. They don't count against the 50-account limit. - **`auth.admins`** names appear in the Directory accounts table as "via the configuration" (`luViaConfig`) once they've signed in. - **The wizard admin** (`setup.go`) is created in `local-users.json` with admin=true, so it's a normal dashboard account. Existing guards: you can't delete your own account (`localUserDelete`), and you can't remove or demote the last administrator (`adminTotal()` counts config admins, runtime directory admins and local admins). Since #852 setup never reopens after that. - **Long dashes:** about 158 literal "—" plus `—` escapes in `web/static/index.html`, a few in `login.html`, `setup.html` and `storage-setup.html`, and some in server error strings shown in the UI (e.g. the local-account name clash in `localusers.go`). - The empty-state text "Only your administrator account exists so far." is wrong on an IdP instance where no local admin exists (seen on cairn-enc). ## Decisions (Nikola, 2026-10-07) 1. **Show config accounts read-only** under Local accounts with a "Config file" badge and no actions. A mockup comes first. 2. **Wizard admin:** keep it as a normal dashboard account, protected by the existing guards. Document it, and recommend an `auth.users` break-glass account for production.
Cordy closed this issue 2026-10-07 08:14:41 +00:00
Sign in to join this conversation.
No labels
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#846
No description provided.