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.
153 lines
8.1 KiB
Markdown
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.
|