# 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: ```text 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](authorization-groups.md). ## 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.