Files
pages/docs/design/auth-backend.md
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

8.1 KiB

Authentication and Authorization Backend

Boundary

Authentication proves an identity. Every authenticator produces the same internal principal_uuid; authenticators never grant document access directly. Authorization is Domain-scoped and evaluates positive grants only:

request -> session -> principal -> Domain membership -> role -> capability

Campus owns trusted identity-provider configuration. A Domain owns membership, roles, grants, session policy, and the default authorization mode. Managed Campus provider metadata is inherited from its controller; secrets remain on the instance that performs authentication and are never federated.

Authentication methods

Method Stable external key Secret location
password normalized username Argon2id verifier in credential table
OIDC exact (issuer, subject) encrypted client secret/config
LDAP (provider UUID, immutable directory attribute) encrypted bind secret
TOTP principal + factor UUID encrypted seed; recovery codes hashed
magic link normalized verified email one-use hashed challenge
device approval requesting-device challenge UUID one-use hashed challenge

OIDC groups and LDAP groups are attributes. Explicit mapping rules may create or remove Membership/Role bindings, but group names are not capabilities. The route policy, internal group schema, /g/ namespace, and endpoint matrix are specified in Endpoint Authorization and Groups.

Core records

  • principals: canonical person/service identity and lifecycle state.
  • principal_identities: unique provider subjects attached to a Principal.
  • auth_credentials: password/TOTP/recovery material and version metadata.
  • domain_memberships: Principal membership in one Domain.
  • auth_roles, auth_role_bindings: Domain roles and membership assignment.
  • groups, group_members, auth_group_role_bindings: Domain-scoped Principal collections and their Role assignment.
  • auth_capability_grants: positive operation grants with typed targets.
  • auth_sessions: opaque, hashed, rotating browser sessions.
  • auth_challenges: short-lived one-use login/MFA/device challenges.
  • auth_audit_log: append-only authentication and policy decisions.

Capabilities use verbs read, create, upload, write, rename, delete, link, manage, and delegate. Targets are domain, quartier, street, spot, path, or object. Locality inheritance is resolved by the address model; an exceptional Page/Object grant does not rewrite the path hierarchy.

Evaluation

  1. Resolve Domain before reading the session.
  2. Hash the opaque cookie and load an unexpired, unrevoked session for that Domain. Reject suspended/quarantined Principals.
  3. Resolve Membership and its Role bindings.
  4. Match the requested verb and target against positive grants. manage includes administrative operations but does not imply delegate.
  5. Record denied sensitive operations and every policy/configuration mutation.

No matching grant means deny. During migration, authorization_mode=legacy leaves existing anonymous behavior intact. Administrators bootstrap an owner, verify access, then switch a Domain to enforcing. New Domains should default to enforcing once the bootstrap flow is complete.

HTTP flows

  • /_/auth/login, /_/auth/logout, /_/auth/callback/oidc/{provider}
  • /u/{username} is the Domain-scoped profile and user-Wiki root. /u/{username}/_/edit is its owner-only profile editor and /_/auth/profile redirects there. Other descendants are ordinary semantic Wiki paths. Usernames exclude dots so the public handle can be derived as {username}.{domain FQDN} without ambiguity.
  • /_/auth/challenge/password, /totp, /magic-link, /device
  • /_/api/v1/auth/session, /principals, /roles, /grants, /audit

Cookies are Secure, HttpOnly, SameSite=Lax, host-only, and contain only a random secret whose SHA-256 hash is stored. Login rotates the session; password or factor changes revoke all Principal sessions. State/nonce/PKCE are mandatory for OIDC. Magic links and device approvals store only a token hash, are single-use, expire quickly, and are bound to Domain and intended action.

TOTP seeds are encrypted with AES-GCM using a 256-bit instance key stored as auth.key beside the Document Store (0600), or derived from PAGESWIKI_AUTH_KEY. Enrollment remains disabled until a valid six-digit code is confirmed. Login challenges expire after five minutes, allow five attempts, and reject reuse of an accepted 30-second counter.

OIDC providers are configured per Domain from the authentication panel. The flow uses discovery, Authorization Code, PKCE S256, state, and nonce, then resolves the subject through UserInfo. A first login may bind (issuer, sub) only to an existing Principal with the same verified email; it never creates a role or capability from provider claims. Client secrets are encrypted with the instance authentication key.

LDAP providers are also Domain-scoped. The implemented login sequence follows the same separation used by Wiki.js' LDAP authenticator:

  1. connect to an ldap:// or ldaps:// endpoint with an 8-second socket deadline; optionally upgrade an ldap:// connection with StartTLS;
  2. bind the configured search service account, or use an anonymous search when both bind fields are empty;
  3. insert the RFC 4515-escaped login into a configured filter containing {{username}}, search below the configured Base DN, and require exactly one result (server size limit 2, time limit 6 seconds);
  4. read an explicitly configured immutable ID, local username, email, and display-name attribute;
  5. bind as the returned user DN with the submitted password. A search result by itself is never accepted as proof of authentication;
  6. resolve the first login by an exact unique local username or email, then persist (provider UUID, immutable ID). Following logins use only that immutable binding. Optional automatic provisioning creates an ordinary member with no local password credential.

The immutable attribute should be entryUUID for common LDAP servers or the binary objectGUID for Active Directory. DN, email, display name, and account name are mutable attributes and therefore are not stable subjects. Bind passwords use the instance authentication-key encryption; leaving the password blank in the settings form preserves the existing encrypted value. TLS certificate validation is on by default, a private CA can be appended as PEM, and disabling validation is an explicit per-Domain administrator action.

The settings panel exposes a saved-configuration login test. User passwords are used only for the user-DN bind and are neither persisted nor logged. Connection admission is bounded to four process-wide LDAP operations. The browser receives the same generic invalid-credentials response for lookup and password failures; the server log retains the provider-side error without the submitted username or password.

SMTP magic links target existing active/read-only Principals by normalized email. The public request response never reveals whether an address exists. Links contain a random token whose hash alone is stored, expire after fifteen minutes, and are consumed atomically once. SMTP credentials use the same encrypted provider-secret storage. Delivery is admitted through a bounded background slot so an SMTP server cannot hold the login request open.

LDAP and SMTP run through bounded worker queues with timeouts; request handlers do not wait indefinitely on an external directory or mail server. A durable authentication-attempt quota keyed by Domain, normalized account identifier, source prefix, and challenge kind remains required before an Internet-facing multi-tenant deployment; bounded provider admission is not a rate limiter.

Delivery order

  1. Common schema, Principal normalization, sessions, RBAC evaluation, audit.
  2. Bootstrap owner plus password/Argon2id and optional TOTP.
  3. OIDC Authorization Code + PKCE.
  4. SMTP magic link and device approval challenges.
  5. LDAP bind/search with immutable identity mapping.
  6. Delegated macaroon capabilities after canonical RBAC is enforced.