What problem are you trying to solve?
OpenKnowledge remote access currently uses a trust-the-tunnel model: an external layer such as Cloudflare Access, Tailscale, or ngrok decides who can reach the server, while every admitted browser or agent receives the same full read-write owner surface.
This works well for a personal knowledge base, but it creates several problems for a shared or company-hosted deployment:
- An externally authenticated user has no distinct identity inside OpenKnowledge.
- All users have full read-write access; there is no read-only or administrative role.
- Document history cannot reliably attribute remote human edits to the person authenticated at the edge.
- Headless MCP agents cannot receive separate, revocable, project-scoped credentials and permissions.
- Revoking one user or agent requires changing the tunnel policy rather than an OpenKnowledge principal.
- Access control cannot be applied consistently across HTTP APIs, collaborative WebSockets, assets, Ask AI, and MCP.
External authentication answers "may this caller reach the server?", but OpenKnowledge still needs an optional way to answer "who is this caller, and what may they do?"
The existing trust-the-tunnel behavior should remain available for simple personal deployments.
Proposed solution
Add an optional authentication and authorization layer for remote mode.
A practical incremental design could be:
1. Normalized principal
Represent every authenticated caller as a principal with fields such as:
- stable subject ID
- display name
- authentication source
- optional groups
- human or service identity
Use this principal for document activity and audit attribution without requiring the application to expose sensitive identity claims in document content.
2. Edge-auth integration first
Allow OpenKnowledge to accept identity from a supported, cryptographically verified edge assertion, for example an OIDC JWT issued by Cloudflare Access or another configured issuer.
This should not blindly trust arbitrary identity headers. The issuer, audience, signature, and expiry must be verified, and the feature should only activate through explicit remote-auth configuration.
Supporting an upstream identity provider first would avoid requiring OpenKnowledge to become a complete identity provider.
3. Project roles
Provide a small initial role model:
reader: browse and search, but cannot mutate contenteditor: edit documents and use normal authoring operationsadmin: configure access and perform destructive or administrative actions
Roles or scopes should be enforced consistently for the REST API, collaboration WebSockets, assets, Ask AI, and MCP tools.
4. MCP service credentials
Support separately revocable service credentials for headless agents. A token should be:
- scoped to one project
- limited to read or write capabilities
- individually named and revocable
- represented as a service principal in activity history
- stored as a hash rather than as the original bearer token
This avoids reusing a human browser session or giving every agent the same tunnel-wide credential.
5. Backward compatibility
Keep the current trust-the-tunnel model as an explicit compatibility mode. Existing local-only projects and remote deployments should continue to work without creating users or configuring an identity provider.
When native authorization is enabled, missing or invalid identity should fail closed.
Possible MVP
A useful first release would not need a full user-management UI:
- verify one configurable OIDC/edge JWT issuer;
- map subjects or groups to
reader, editor, or admin in configuration;
- apply those roles to HTTP, WebSocket, and MCP operations;
- attribute remote changes to the verified principal;
- provide CLI-managed, project-scoped MCP service tokens.
A later release could add an interactive OIDC login flow, settings UI, group mapping, invitations, and richer document-level permissions.
Area
Other
Alternatives considered
Cloudflare Access, ngrok OAuth, or Tailscale alone
These correctly protect network admission and remain valuable. They do not give OpenKnowledge per-user roles, application-level attribution, or separately revocable agent identities.
HTTP Basic Authentication
Basic Auth can protect headless MCP traffic, but it is unsuitable as the main browser solution because live editing uses WebSockets. It also supplies only a shared credential, not useful user identity or project roles.
Separate local clones synchronized through GitHub
This gives GitHub-level repository permissions and individual commit identity, but it is not the same as multiple users working against one live OpenKnowledge server. Changes arrive through Git synchronization rather than the real-time collaboration channel.
Reverse-proxy path rules
A proxy can distinguish /mcp from the browser UI, but it cannot safely authorize individual OpenKnowledge operations or express reader/editor/admin permissions across the collaboration protocol.
What problem are you trying to solve?
OpenKnowledge remote access currently uses a trust-the-tunnel model: an external layer such as Cloudflare Access, Tailscale, or ngrok decides who can reach the server, while every admitted browser or agent receives the same full read-write owner surface.
This works well for a personal knowledge base, but it creates several problems for a shared or company-hosted deployment:
External authentication answers "may this caller reach the server?", but OpenKnowledge still needs an optional way to answer "who is this caller, and what may they do?"
The existing trust-the-tunnel behavior should remain available for simple personal deployments.
Proposed solution
Add an optional authentication and authorization layer for remote mode.
A practical incremental design could be:
1. Normalized principal
Represent every authenticated caller as a principal with fields such as:
Use this principal for document activity and audit attribution without requiring the application to expose sensitive identity claims in document content.
2. Edge-auth integration first
Allow OpenKnowledge to accept identity from a supported, cryptographically verified edge assertion, for example an OIDC JWT issued by Cloudflare Access or another configured issuer.
This should not blindly trust arbitrary identity headers. The issuer, audience, signature, and expiry must be verified, and the feature should only activate through explicit remote-auth configuration.
Supporting an upstream identity provider first would avoid requiring OpenKnowledge to become a complete identity provider.
3. Project roles
Provide a small initial role model:
reader: browse and search, but cannot mutate contenteditor: edit documents and use normal authoring operationsadmin: configure access and perform destructive or administrative actionsRoles or scopes should be enforced consistently for the REST API, collaboration WebSockets, assets, Ask AI, and MCP tools.
4. MCP service credentials
Support separately revocable service credentials for headless agents. A token should be:
This avoids reusing a human browser session or giving every agent the same tunnel-wide credential.
5. Backward compatibility
Keep the current trust-the-tunnel model as an explicit compatibility mode. Existing local-only projects and remote deployments should continue to work without creating users or configuring an identity provider.
When native authorization is enabled, missing or invalid identity should fail closed.
Possible MVP
A useful first release would not need a full user-management UI:
reader,editor, oradminin configuration;A later release could add an interactive OIDC login flow, settings UI, group mapping, invitations, and richer document-level permissions.
Area
Other
Alternatives considered
Cloudflare Access, ngrok OAuth, or Tailscale alone
These correctly protect network admission and remain valuable. They do not give OpenKnowledge per-user roles, application-level attribution, or separately revocable agent identities.
HTTP Basic Authentication
Basic Auth can protect headless MCP traffic, but it is unsuitable as the main browser solution because live editing uses WebSockets. It also supplies only a shared credential, not useful user identity or project roles.
Separate local clones synchronized through GitHub
This gives GitHub-level repository permissions and individual commit identity, but it is not the same as multiple users working against one live OpenKnowledge server. Changes arrive through Git synchronization rather than the real-time collaboration channel.
Reverse-proxy path rules
A proxy can distinguish
/mcpfrom the browser UI, but it cannot safely authorize individual OpenKnowledge operations or express reader/editor/admin permissions across the collaboration protocol.