Skip to content

Console and authentication

Operator surface (/console/*), permission catalog and roles, data security (groups + scopes), system settings, and the two authentication modes.

Console (admin)

  • Entry: header Console opens /console when outside console routes; on /console/* the same control reads Exit Console and returns home (/). Exit Console is also pinned at the bottom of the console sidebar (scrollable nav above). /console/* requires permission all, any console:* from GET /api/auth/me, or JWT realm role admin (OIDC) / full catalog for IdP admins. Sidebar (main app and console) shows a link only when canAccessPath matches that route against the union of frontend_route_patterns from GET /api/auth/permission-catalog (same rules as the main layout route gate), in addition to feature toggles where applicable.
  • Console overview (/console): Introduces console sidebar tools only—permissions, data security, data sources, users & feature toggles, settings; cards link when canAccessPath allows; quick links to Permissions and Access groups when those permissions apply; optional nudge when the catalog still has only all (until openkms_permissions_onboarding_dismissed is set).
  • Permission management (/console/permission-management): Permission catalog is stored in security_permissions; the page loads rows from GET /api/admin/security-permissions (includes id for edit/delete). Under Roles, All selects catalog-only mode (add/edit/delete permission rows). Choosing a named role shows checkboxes to draft which keys that role receives; Save role permissions calls PUT /api/admin/security-roles/{id}/permissions once—no auto-save on each toggle. Switching roles with unsaved changes prompts to discard. Migrations seed all when the catalog table is empty and backfill default pattern rows for every hinted operation key (a2b3c4d5e6f7); admins may add keys via Add permission, Add missing suggested keys (from operation_key_hints on GET /api/admin/permission-reference), or POST /api/admin/security-permissions, using the in-page Route & API reference (and Operation keys tab) for path patterns. Roles may only assign keys that exist in security_permissions. The built-in all row cannot be edited or deleted. Migration seeds the admin role with all; member is created on first non-admin local sign-in (also starts with all). You cannot remove all from a role that still has only all in one step—add another permission, save, then remove all. Local: user_security_roles synced from is_admin. OIDC: JWT realm_access.roles match security_roles.name; realm admin bypasses permission checks.
  • Data security (/console/data-security/groups, /console/data-security/groups/:id/access, /console/data-security/data-resources): requires console:groups. Access groups, data resources, and per-group resource scopes (channels, KBs, wiki spaces, evaluation datasets, datasets, object types, link types, data resource attachments) are editable in both local and OIDC modes. Assigning local users to access groups is available only when OPENKMS_AUTH_MODE=local (OIDC: membership is outside this app; Console shows scopes only on the group data access page). Data resources CRUD via /api/admin/data-resources; kinds: document, knowledge_base, evaluation_dataset, dataset, object_type, link_type. Enforcement: OPENKMS_ENFORCE_GROUP_DATA_SCOPES (default false); when true, local non-admin users with group membership see the union of legacy ID allow lists or rows matching any granted data resource for that entity family (documents: channel subtree + metadata.* / channel_id JSONB filters; KBs: anchor or kb_id/name; others: id keys in attributes). Users with no group rows are not filtered (legacy). OIDC: scope enforcement skipped in this phase.
  • Data Sources (/console/data-sources): console:data_sources (or admin). Datasets and schema (/ontology/datasets, /ontology/object-types, /ontology/link-types): console:datasets / console:object_types / console:link_types or ontology:read / ontology:write as applicable (API uses require_any_permission); System Settings, Users & Roles, Feature Toggles remain console:* (or admin).
  • Users & Roles (/console/users): requires console:users. Local auth: list users, toggle is_admin (syncs security role links), delete/add users. OIDC auth: read-only notice.
  • System settings (/console/settings): console:settings (or admin). GET /api/public/settings / PUT /api/public/settings load and persist system_settings (Postgres singleton row): system_name, default_timezone, api_base_url_note (optional note only; SPA API URL remains build-time). A PUT whose trimmed system_name would be empty is stored as openKMS. GET /api/public/system returns { "system_name" } without authentication (strict middleware allowlist); the value is the trimmed DB field and may be "". The sidebar title stays blank until that response arrives, then shows openKMS when the name is empty or whitespace (otherwise the returned name); on fetch failure it shows openKMS. After saves, notifySystemSettingsUpdated triggers the same fetch (custom event). Migration seeds row id=1 and attaches GET/PUT patterns to console:settings for strict API enforcement.
  • Feature toggles: articles, knowledgeBases, wikiSpaces, objectsAndLinks, taxonomy (default-enabled) and evaluationDatasets (default-disabled, experimental) – persisted in PostgreSQL (feature_toggles table), shared across all users/devices
  • GET /api/feature-toggles (authenticated) returns current toggle state
  • PUT /api/feature-toggles requires console:feature_toggles (or JWT admin)

Permission catalog (canonical keys)

Defined in backend/app/services/permission_catalog.py; seeded into security_permissions by migration. Roles may only assign keys that exist in the catalog.

Family Keys
Console console:access, console:users, console:groups, console:permissions, console:settings, console:feature_toggles, console:data_sources, console:datasets, console:object_types, console:link_types
Documents documents:read, documents:write
Document channels channels:read, channels:write
Articles articles:read, articles:write
Knowledge bases knowledge_bases:read, knowledge_bases:write
Evaluation evaluation:read, evaluation:write
Wiki wikis:read, wikis:write
Ontology ontology:read, ontology:write
Knowledge map taxonomy:read, taxonomy:write
Catch-all all (built-in admin key; cannot be edited or deleted)

Authentication

  • OIDC mode (default): any OIDC IdP – Authorization Code + PKCE in browser (oidc-client-ts); RP-initiated logout when the IdP exposes end_session_endpoint
  • Local mode (OPENKMS_AUTH_MODE=local): sign-up when OPENKMS_ALLOW_SIGNUP (exposed as allow_signup on GET /api/auth/public-config); sign-in with username or email + password; users stored in PostgreSQL; HS256 JWT + session cookie; no built-in admin password (first signup or OPENKMS_INITIAL_ADMIN_USER match gets admin). The UI uses public-config so it stays aligned with the server even if VITE_AUTH_MODE differs.
  • openkms-cli: OIDC client credentials (Bearer) or, in local mode, HTTP Basic (OPENKMS_CLI_BASIC_*)
  • Profile (/profile): authenticated users see display name, email (if present), administrator yes/no, realm roles, and resolved permissions (local users: DB keys such as all or granular console:*; OIDC IdP admins receive the full catalog); data from GET /api/auth/me. Linked from the header user menu.
  • Settings (/settings): API keys — create, list, and revoke personal API keys for assistants and scripts (POST / GET / DELETE /api/auth/api-keys); the full secret is shown only once at creation. Linked from the header user menu (Settings).
  • OIDC + API traffic: the token provider used by getAuthHeaders() returns the access token only (no setUser / no POST /sync-session + GET /api/auth/me on every token read). Session sync and profile refresh run from OIDC init and UserManager user events. The SPA permission-catalog effect depends on a stable username / roles / permissions key so equivalent user objects do not refetch in a loop.
  • Protected routes: under MainLayout, all except home (/) require auth; /login and /signup are separate routes. Unauthenticated users on / see the static marketing home; on any other path they see "Authentication Required". Authenticated users without JWT admin / all must match the union of frontend_route_patterns from GET /api/auth/permission-catalog for their keys (paths / and /profile are always allowed); otherwise "Access denied" with a link home.

Static home (landing page)

  • Public landing page for non-authorized users
  • Pain points: knowledge scattered, unstructured content, manual work
  • Benefits: centralized document hub, RAG-ready knowledge bases, fine-grained roles and console for permissions / data security / platform settings
  • Functionalities sections: document management, articles, knowledge bases (including semantic search when pgvector is configured), ontology & graph (datasets, object/link types, optional Neo4j), pipelines & automation (jobs, per-channel pipelines, model linkage)