Files
pages/docs/design/auth-backend.md
T
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

153 lines
8.1 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
- `/_/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.