CAIPE Knowledge Base - Programmatic & External Access (Proposal for Discussion)

[ankbat]

Status: Proposal for discussion (RFC)

Scope: Let external/automated clients (CLI, scripts, partner services) ingest into and search Knowledge Bases with consistent, team-scoped RBAC.

• KB access today is effectively browser-only; there is real demand to use it programmatically (CLI, automation, partner services, CI).
• The building blocks already exist (OpenFGA ReBAC, an ext-authz bridge, and a KB MCP route), but a couple of gaps make external, per-team-scoped access awkward.
• We propose two things: (1) a public entry that accepts Authorization: Bearer for programmatic clients, and (2) aligning the RAG server's authorization for service-account callers with what the OpenFGA model and the ext-authz bridge already express, so users and service accounts are scoped identically for both ingest and search.
• This is an RFC. Open questions for maintainers at the end.

---

1. Motivation

Today Knowledge Base access is effectively browser-only. There is growing demand to use the KB programmatically: a CLI/automation that ingests and queries, external/partner services that push content into a team's KB, and CI jobs that keep a KB in sync. The goal: a client authenticating as either a user or a service account should get the same, correctly team-scoped access to both ingest and search.

2. Current architecture (as-is)

Entry points

Surface	Exposure	Auth
UI BFF /api/rag/*	public (the app's front door)	browser session today
rag-server REST /v1/*	in-cluster only (ClusterIP, no route)	validated JWT, then its own RBAC
rag-server MCP /mcp (FastMCP)	in-cluster, fronted by agentgateway route /mcp/knowledge-base	JWT auth + agentgateway ext-authz

Two RBAC layers

1. Invocation gate: can this caller call this tool/endpoint at all. Enforced for tool calls by agentgateway -> openfga-authz-bridge.
2. Result filter: which datasources' documents/chunks are returned or writable. Enforced inside rag-server (get_accessible_datasource_ids / inject_kb_filter).

3. Gaps we found

• Gap A - service-account callers are not scoped consistently. The RAG server authenticates client-credentials (service-account) tokens but does not apply the same per-resource OpenFGA scoping to them that it applies to human users, and that the ext-authz bridge already applies. The OpenFGA model already defines service_account as a valid principal on knowledge_base/data_source, and the bridge already keys on the service_account subject; the RAG server's own path does not yet build that principal. Net: service-account access is not consistently team-scoped on the REST/MCP path. (Specific mechanics shared with maintainers via the security channel rather than here.)
• Gap B - result filtering lives in the RAG server. For search, which chunks are returned is decided inside the RAG server. So consistent scoping for service-account callers depends on Gap A being resolved. Routing through the gateway gates invocation but cannot scope search results.
• Gap C - generic datasource upsert vs. ownership tuples. POST /v1/datasource persists owner_team_slug to config but, unlike the /v1/ingest/* endpoints, does not call write_datasource_ownership, so config and OpenFGA can drift (a datasource with an owning team in config but no ownership tuples).
• Gap D - no ingest MCP tool. The KB MCP server exposes search, fetch_document, list_datasources, and graph reads, but no ingest tool. Ingestion is REST-only (/v1/ingest/*).
• Gap E - no programmatic public entry. The UI BFF's /api/rag/* proxy accepts a browser session only, not Authorization: Bearer, and the RAG server REST API is in-cluster only. So there is no clean public entry for CLI/automation.

4. Proposed architecture (to-be)

Principle

One public entry, one authz model, identity preserved to the data layer.

• Public entry: the UI BFF (already public), extended to accept Authorization: Bearer for programmatic clients.
• One authz model: OpenFGA ReBAC, applied uniformly to user and service_account principals, at both the invocation gate and the result filter.
• The caller's identity is carried unchanged from the front door to the data layer, and every check keys on it.

Access flow

external caller (Bearer = user JWT  OR  per-partner service-account JWT)
      |  Authorization: Bearer
      v
UI BFF /api/rag/*        validate JWT + role gate + forward same token
      v
rag-server (REST or MCP)
      |  OpenFGA principal = user:{sub}  OR  service_account:{sub}
      v
OpenFGA check:  can_ingest / can_read on knowledge_base | data_source
      v
scoped to the caller's team(s)
  ingest -> writes ownership tuples for owner_team
  search -> returns only readable chunks

Sequence - ingest (REST via BFF, primary path)

1. Client  ->  BFF      POST /api/rag/v1/ingest/local-file  (Bearer + owner_team_slug)
2. BFF                  validate JWT + role gate
3. BFF     ->  rag      forward request (same Bearer)
4. rag                  resolve principal = user OR service_account
5. rag     ->  FGA      check can_ingest on knowledge_base
6. FGA     ->  rag      allow
7. rag     ->  FGA      write ownership tuples (owner_team)
8. rag     ->  BFF      datasource_id
9. BFF     ->  Client   200 datasource_id

Sequence - search (REST via BFF; result filtering happens in rag-server)

1. Client  ->  BFF      POST /api/rag/v1/query  (Bearer + query)
2. BFF                  validate JWT + role gate
3. BFF     ->  rag      forward request (same Bearer)
4. rag     ->  FGA      list accessible data_sources (can_read) for principal
5. FGA     ->  rag      ids scoped to caller's team(s)
6. rag                  vector search filtered to those ids
7. rag     ->  BFF      chunks (only readable)
8. BFF     ->  Client   results

Sequence - optional MCP via agentgateway (reuses the existing /mcp/knowledge-base route)

1. Client  ->  BFF      MCP tools/call: ingest  (Bearer)
2. BFF     ->  GW       forward to /mcp/knowledge-base  (same Bearer)
3. GW      ->  bridge   ext-authz Check
4. bridge  ->  FGA      can_call tool knowledge-base/ingest  (user OR service_account)
5. FGA     ->  bridge   allow
6. GW      ->  rag/mcp  tools/call: ingest
7. rag     ->  FGA      can_ingest + write ownership tuples
8. rag     ->  GW       result   (GW -> BFF -> Client)

The agentgateway KB route already exists (deploy/agentgateway/config.yaml, /mcp/knowledge-base to rag-server:9446/mcp, with ext-authz to openfga-authz-bridge). It is wired but bypassed by default. The bridge gates invocation; the result filter for search still lives in the RAG server (Gap B), so Gap A must be resolved for scoped search regardless of path.

Core change (the single unlock)

Align the RAG server's authorization so service-account callers are scoped like users: build a service_account principal (matching the ext-authz bridge) and run the same OpenFGA checks. Preserve a narrow trusted-service allowance for the in-cluster connector ingestors that legitimately need cross-KB writes (an allowlist of trusted client IDs or a dedicated role, rather than a blanket exception). This makes ingest and search behave identically for users and service accounts, with no new BFF and no MCP-client machinery.

Identity options (both scoped by OpenFGA team grants)

• User: OAuth Authorization-Code + PKCE (as the CAIPE CLI already implements).
• Per-partner service account: one confidential client per external party, client_credentials; scoped by service_account team grants. Enabled by the core change.

Optional (secondary)

• Expose ingestion as an MCP tool so it can also flow through the agent/gateway path (invocation-gated by a tool object for ingest). Not required for the REST path once the core change lands.

5. Why

• Consistency: the RAG server aligns with the OpenFGA model (which already defines service_account) and with the gateway bridge (which already scopes it).
• Least privilege: external/multi-tenant callers no longer need an over-broad credential; a per-partner credential is limited to that partner's team.
• Simplicity: the public REST path stays a plain HTTP forward; no MCP client or separate BFF needed for correct scoping.
• Uniformity: the same change makes ingest and search behave identically for users and service accounts.

6. Proposed change set

1. Align RAG-server RBAC for service accounts: build the service_account principal and run the standard OpenFGA checks, with a trusted-service allowlist/role to preserve the in-cluster connector ingestors that currently need cross-KB writes.
2. BFF public entry accepts Authorization: Bearer on /api/rag/* (in addition to the browser session): validate the JWT, enforce the role gate, forward the same token to the RAG server.
3. POST /v1/datasource writes ownership tuples when owner_team_slug is set (mirror the ingest endpoints), or document it explicitly as admin/connector-only.
4. (Optional) ingestion MCP tool with a tool object for invocation-gating on the agent/gateway path.

7. Open questions for maintainers

1. Is the current service-account behavior on the RAG-server path intentional for trusted in-cluster connectors? If so, is an allowlist / trusted-role the preferred way to keep that while scoping other service accounts?
2. Preferred external identity model: per-partner service accounts, real users, or both?
3. Should ingestion be exposed as an MCP tool (agent/gateway path), or kept REST-only behind the BFF?
4. Any objection to POST /v1/datasource writing ownership tuples (vs. documenting it as connector-only)?

---

Appendix - relevant areas (upstream)

• ai_platform_engineering/knowledge_bases/rag/server/src/server/rbac.py - RAG-server authorization (principal resolution, per-resource checks, result filtering)
• ai_platform_engineering/knowledge_bases/rag/server/src/server/restapi.py - /v1/ingest/*, /v1/datasource, /v1/query, FastMCP mount at /mcp
• ai_platform_engineering/knowledge_bases/rag/server/src/server/tools.py - MCP tools (search/fetch/list/graph; no ingest)
• deploy/openfga/model.fga - knowledge_base, data_source, service_account, tool types
• deploy/openfga/bridge/main.py - ext-authz caller keying (service_account vs user)
• deploy/agentgateway/config.yaml - /mcp/knowledge-base route + ext-authz
• ui/src/app/api/rag/[...path]/route.ts - BFF RAG proxy (public entry)