ADR: First-party identity (Operator / Owner / Administrator / Member)

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Context

Bookclerk historically split identity into a shared operator token (control plane) and portal identities keyed by external (provider, external_user_id) from claim tickets or integration authenticateUser. Bookstore connect via bookclerk auth could create store accounts with no portal link. The product goal is a self-hostable first-party User as the security principal for library and Accounts, without requiring Redis or an external IdP.

Operators who already run a directory (Authentik, Keycloak, Entra) or want social sign-on need Bookclerk to consume upstream OIDC/OAuth while still issuing tokens to Audiobookshelf. True token passthrough (ABS trusts the upstream issuer) is not supportable.

Decision

Principals

Principal Powers
Operator Control plane via shared operator token + durable hashed sessions. Cannot connect bookstore sources. Can impersonate any User. Creates the linked Owner on bootstrap. Never an OAuth/OIDC subject — not JIT’d, linked, or offered on the SSO login page. SPA operator-token paste is offered only before an active Owner exists; afterwards use tray handoff or Owner elevate.
Owner Super-user (multiple allowed). Administrator caps plus elevate to Operator after step-up (IdP prompt=login, passkey, or local password). Last active Owner cannot be demoted/disabled/deleted. Non-elevated Owners may provision Members and Administrators, not other Owners. May be mapped from an upstream IdP role.
Administrator Normal User + admin caps (provision Members only; cannot create, assign, or manage Administrator or Owner). Cannot elevate. May be JIT / role-synced from an IdP.
Host (removed 2026-11-18) Folded into Member: a Member who owns a node now administers it as described here, so this role is gone. As decided then: Member who owns library nodes: changes their budgets, drain switch, and name, and sees the Status page for the library plus those nodes. Placement labels stay with the operator. Assigned by an Owner or the Operator, never by an Administrator; promote to Administrator to trust the user with other users' work. May be mapped from an IdP role (ranked between Administrator and Member).
Member Normal User; may connect sources under policy. May be JIT from IdP or social provision policies.

Federation and OIDC

  • Keep claim tickets / invite magic links (/invite?ticket=…) and integration authenticateUser even when a User has no local password yet. External bookstore/integration accounts are connections, not login principals.
  • Optional contact email on users supports invites and SSO link_by_email.
  • Bookclerk is the OIDC authorization server for Audiobookshelf (core AS; plugins do not implement the protocol). Tokens are bound to a User, never minted from the operator token alone. Plugin-provided relying-party clients (ABS and later guests) are declared by the plugin and gated with an enable toggle; see plugin-provided OIDC clients.
  • Bookclerk may optionally act as an OIDC/OAuth relying party (identity broker) for one or more upstream providers. Upstream login creates or links a first-party User; ABS still trusts Bookclerk’s issuer. IdP passwords are never stored. Requiring an external IdP remains a non-goal.
  • Upstream roles map only to owner / administrator / member (never operator). Per-provider provision modes: mapped_role, any, allowlist, invite_only.
  • Owner elevation uses IdP step-up, a local passkey, or a Bookclerk password — not a copied SSO password.
  • Passkeys (WebAuthn) are the User-plane hatch when an IdP is down. The Operator token remains host break-glass. The relying party ID is a hostname (integrations.public_origin, or localhost on loopback) — never a raw IP. Passkeys are named at registration. Optional TOTP (authenticator app) is a second factor for password login only; passkey sign-in does not also require a TOTP code. Owners/operators may set daemon.auth.require_second_factor so password login must use TOTP or the user must sign in with a passkey.

CLI

  • Remove the entire bookclerk auth command group. Store connect lives in the User SPA Accounts UI only. Operational account listing / scan toggles move under library (or equivalent) without creating unlinked store credentials.

Small-VPS constraint

Use the existing database abstraction / SQLite platform path and bounded cleanup. Baseline must not require Redis, an external IdP, or another always-on service.

Phases

Core identity (Phases 0–5) shipped in #129 closing #117. Owner/RBAC Settings UI and provisioner matrix landed in #150. Optional multi-IdP broker + WebAuthn (Phase 6) landed in #152.

Phase Scope Status
0 Durable hashed operator sessions; portal logout revoke; atomic claim redeem; Secure cookies; daemon.trusted_proxies Done (#129)
1 users schema; migrate portal_identities; ban CLI/operator store-link; prefs user:{id} Done (#129)
2 Owner elevate-to-Operator (password / IdP step-up / passkey); Operator / elevated impersonate User Done (#129, #150, #152)
3 Bootstrap Owner; invite magic links; Argon2id; federation without local password Done (#129, #150)
4 Core OIDC AS (code + PKCE) for ABS Done (#129)
5 CSRF/Origin; session list/revoke; audit log; account-link invariant; proxy TLS docs Done (#129)
6 Optional multi-IdP OIDC RP (broker); WebAuthn passkeys Done (#152)

Consequences

  • Portal cookies and /api/portal/* resolve to a first-party users row.
  • Operator prefs subject remains operator; user prefs use user:{id}.
  • Docs: sign-in.md, the UI page (tray), operations.md, integrations.md, database.md, plugin-provided OIDC clients.
  • Operator tray login never puts the durable token in a GET URL. Open Bookclerk mints a short-lived (default 180 s) hashed one-time loopback code (POST /api/auth/tray-handoff/prepare then GET /api/auth/tray-handoff?code=). A same-host reverse proxy cannot complete that handoff; the operator session cookie is set on localhost only.
  • The Owner / Administrator / Member role split is greenfield. There is no in-place upgrade that promotes existing Administrators to Owner. Testing and development deployments that already have a library.db from before this change must recreate it (cargo reset --yes, or delete $BOOKCLERK_FILES_DIR and re-bootstrap). The OIDC RP / passkey tables in this cut are likewise greenfield: testers should reset the database before validating SSO and passkey enrollment. Production hosts should plan a fresh files directory / restore from a compatible backup rather than expecting a silent role migration.

Non-goals

  • Requiring an external IdP or Redis
  • Configuring ABS to trust an upstream issuer (token passthrough)
  • OAuth-linking or JIT of the Operator account
  • Storing IdP passwords, or requiring a Bookclerk password for SSO-only Users
  • Using bookstore OAuth (Audible, etc.) as enterprise SSO
  • SCIM/push provisioning in this cut (login-time JIT/sync is enough)
  • Spatial/Atmos DRM
  • Reopening #116

Source: docs/adr/first-party-identity.md at main · View as Markdown