LeoVasanko/paskia
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Docs: multi-realm current state

Browse Source 
README quick start and configuration updated for init/serve split and
paskia.kantadb; API.md server-config endpoints replaced with admin realm
CRUD and the well-known webauthn endpoint; proxy guides point at the
realm auth-host setting; oidc.md documents per-realm issuers; MultiSite.md
rewritten from the implementation plan into documentation of the shipped
mechanics, policy model, and design rationale.
This commit is contained in:
LeoVasanko
2026-09-06 15:13:10 +00:00
parent 8ccc257f44
commit 2baebc4072
9 changed files with 365 additions and 583 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+18 -4
View File
@@ -72,8 +72,12 @@ E.g. Org admin cannot see anything of the other orgs that he has no admin access
| PATCH | /auth/api/admin/oidc-clients/{uuid} | Update OIDC client | 200/401/403 |
| PATCH | /auth/api/admin/oidc-clients/{uuid}/reset-secret | Reset client secret | 200/401/403 |
| DELETE | /auth/api/admin/oidc-clients/{uuid} | Delete OIDC client | 200/401/403 |
| GET | /auth/api/admin/server-config/ | Get server config | 200/401/403 |
| PATCH | /auth/api/admin/server-config/ | Update server config | 200/401/403 |
| GET | /auth/api/admin/realms/ | List realms (rp-ids) with derived URLs | 200/401/403 |
| POST | /auth/api/admin/realms/ | Create realm `{rp_id, rp_name?, auth_host?, origins?}` | 200/400/401/403 |
| PATCH | /auth/api/admin/realms/{rp_id} | Update realm rp_name/auth_host/origins | 200/400/401/403 |
| DELETE | /auth/api/admin/realms/{rp_id} | Delete realm (refused while credentials remain) | 200/400/401/403 |
Realm endpoints require the `auth:admin` permission; writes additionally require recent authentication (5 minutes). Changes are validated cross-realm and apply immediately.
### WebSockets: /auth/ws/*
@@ -86,7 +90,9 @@ E.g. Org admin cannot see anything of the other orgs that he has no admin access
These are for internal use only, but are documented here because they are the core piece in all passkey operations.
### Auth host mode (--auth-host)
### Auth host mode (dedicated auth site)
A realm may configure a dedicated authentication host (auth-host, a subdomain of the rp-id), either at bootstrap (`paskia init --auth-host`) or via the Realms admin panel.
#### On the auth host:
- The Web UI is served at site root instead of /auth/* (that redirects to root paths)
@@ -98,4 +104,12 @@ These are for internal use only, but are documented here because they are the co
- /auth/api/* is served normally.
- /auth/api/user/*, /auth/api/admin/*, and /auth/ws/* don't exist.
The WebSocket connections are directed to auth host, and must have an allowed origin corresponding to the host where the user is logging in, that the session is tied with.
The WebSocket connections are directed to the auth host, and must have an allowed origin corresponding to the host where the user is logging in, that the session is tied with.
#### Shared auth host across realms
When one realm has an auth host, other realms without their own use it as their *effective* auth host: their WebSocket and cross-device flows are directed there, but their own `/auth/` still serves the full profile (host mode is keyed off the realm's *own* auth host only). `/auth/api/settings` exposes both: `auth_host` (effective) and `own_auth_host` (this realm only, null when unset).
### Related Origin Requests: /.well-known/webauthn
`GET /.well-known/webauthn` returns `{"origins": [...]}` listing the realm's related origins (configured origins on domains unrelated to the rp-id), per WebAuthn Related Origin Requests. Browsers fetch this from the rp-id domain when an unrelated origin runs a ceremony with this realm's rp-id. Returns 404 when the realm has no related origins. If the rp-id's main site is hosted elsewhere, serve the JSON statically there (copy it from this instance).