WeKnora/website-docs/04-api
Ochan Kwon e0712df3e0
feat(mcp): let callers without a browser obtain MCP OAuth tokens (#4229)
WeKnora runs behind other applications: they sign their users in and
call WeKnora with a tenant API key and X-External-User-ID, and WeKnora
keeps sessions and MCP OAuth tokens per external user. When an agent
uses an OAuth-protected MCP service, the only way to get that user's
token is the browser authorization code flow, and in this deployment
the user never sees WeKnora, so there is no browser to complete it.
Independently, an OAuth MCP service can only get its client through
dynamic client registration (RFC 7591), so authorization servers
without a registration endpoint cannot be used at all ("server does not
support dynamic client registration"), and servers that allow a grant
only to clients an administrator registered refuse a dynamic one.

JWT bearer grant. The application in front already knows who the user
is. POST /api/v1/mcp-services/:id/oauth/assertion lets it present a
signed assertion of that identity, such as the Identity Assertion JWT
Authorization Grant (ID-JAG) used by MCP's Enterprise-Managed
Authorization extension. WeKnora sends it to the service's
authorization server with the JWT bearer grant (RFC 7523) and stores
the token exactly like the callback does, so status, revoke, runtime
connections and, when the response carries a refresh token, refresh
use it unchanged. The assertion is forwarded unread; validating it is
up to the authorization server. The request reuses the principal from
authorize-url, the SSRF-safe HTTP client and the callback's connection
recycling, and the client the service already has. It does not run
dynamic client registration, which describes a redirect-based client;
without a client it answers 400. The token request outlives the caller,
so a token issued for an assertion that can only be used once is not
lost. A 4xx response other than 408 and 429, or a 2xx response carrying
an OAuth error, answers 400 with the OAuth error code and is logged; a
5xx, 408 or 429 response or a network failure answers 500. Request
logging masks the assertion field.

Pre-registered client. auth_config.client_id names a client registered
with the authorization server in advance, and client_secret is its
secret for a confidential client. When client_id is set it takes the
place of dynamic registration everywhere a client is read: the
authorization URL, the code exchange, the assertion grant and runtime
connections with their token refreshes. The values live on the service
rather than in mcp_oauth_clients, because a refresh rejected with
invalid_client deletes that row so the next authorization registers
again; an administrator's client would silently disappear. client_id is
non-secret: it is set through the main PUT, where an empty value clears
it, and returned in auth_config. client_secret follows api_key and
token: encrypted at rest, never returned, accepted in the create body,
and changed afterwards through the credentials subresource. Changing
client_id rebuilds the service's connections, and a connection built
with a pre-registered client is not treated as holding a replaced
registration when an authorization recycles connections. The MCP
service dialog adds optional Client ID and Client Secret fields to the
OAuth section, in all six locales.

Nothing changes for existing services: with client_id empty every
existing path reads the stored registration and registers dynamically
as before, and the authorization code flow, its state, the callback and
the dynamic registration request are untouched. The authorization
server HTTP client is moved into a function that both paths call.
2026-10-13 16:37:24 +08:00
..
01-api-overview.md docs(api): clarify knowledge-search scope union of knowledge_base_ids and knowledge_ids (#4191) 2026-10-12 17:40:56 +08:00
02-api-agent-mcp.md feat(mcp): let callers without a browser obtain MCP OAuth tokens (#4229) 2026-10-13 16:37:24 +08:00
02-api-auth.md feat(auth): 新增仅限邀请注册档位 (#3900) 2026-09-30 13:32:55 +08:00
02-api-channels.md revert: take the plugin system back out of main 2026-09-26 14:58:18 +08:00
02-api-chat.md docs(api): clarify knowledge-search scope union of knowledge_base_ids and knowledge_ids (#4191) 2026-10-12 17:40:56 +08:00
02-api-chunks.md feat(chat): open cited documents at the cited passage (#3700) 2026-09-25 13:26:16 +08:00
02-api-faq-wiki.md fix(wiki): resolve titles for unloaded backlinks (#3931) 2026-10-09 10:50:52 +08:00
02-api-infra.md revert: take the plugin system back out of main 2026-09-26 14:58:18 +08:00
02-api-knowledge.md docs: explain knowledge upload folder paths (#4177) 2026-10-12 14:30:07 +08:00
02-api-memory.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-model-system.md perf(embedding): batch Qwen3-VL message inputs (#4126) 2026-10-10 16:07:29 +08:00
02-api-org.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-sandbox-skills.md feat(sandbox): Docker 后端支持交互式终端 (#4023) 2026-10-10 21:38:03 +08:00
02-api-system.md feat(models): add system admin model catalog console (#3662) 2026-09-24 16:31:45 +08:00
02-api-tenant.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00