Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
160 lines
8.6 KiB
Markdown
160 lines
8.6 KiB
Markdown
# 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
|
|
|
|
Implementation clarification (2026-11-01): clients requesting JSON from
|
|
`POST /_/auth/login` (or `/totp`) receive an opaque Bearer session rather than
|
|
extracting a browser cookie. The remote CLI follows this existing flow and the
|
|
same Domain membership/capability checks; see [remote CLI](ja/remote-cli.md).
|
|
It does not implement an OIDC device handoff yet. The cookie descriptions below
|
|
apply to browser sessions, not a requirement for all HTTP clients.
|
|
|
|
- `/_/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.
|