098 Architecture: Enterprise RBAC for CAIPE Platform
Spec: 098 — Enterprise RBAC for Slack and CAIPE UI (098-enterprise-rbac-slack-ui)
Date: April 2026
Supersedes: 093 architecture (historical reference)
Canonical Architecture Diagram
This is the single source of architecture truth for Enterprise RBAC. Numbered arrows correspond to the flow table below the diagram.
Flow Table
| Step | From | To | Description |
|---|---|---|---|
| ① | User | Slack / Webex / Admin UI | User sends command or performs admin action |
| ② | Entry point | Bot Backend / BFF | Event delivered with user context (Slack signature, OAuth, NextAuth session) |
| ③a | Enterprise IdP | Keycloak | Federation: Okta/Entra groups and identity brokered into Keycloak |
| ③b | Bot/BFF | Keycloak | OBO token exchange (RFC 8693): bot obtains JWT with sub=user, act=bot, groups, roles, scope, org |
| ④a | Bot/BFF | Keycloak AuthZ (PDP) | UI/Slack authorization: checks JWT + requested capability against 098 matrix → allow/deny |
| ④b | Bot/BFF | Agent Gateway | MCP/A2A/agent authorization: AG validates JWT, applies CEL policy → allow/deny |
| ⑤a | Agent Gateway | Supervisor → Agents | Authorized request routed to domain agents |
| ⑤b | Agents | Agent Gateway → MCP | Agent MCP tool calls re-enter AG for tool-level RBAC (FR-016) |
| ⑥ | PDP / RAG | MongoDB + Keycloak | Hybrid store: Keycloak holds authz policies (resources, scopes, permissions) and Slack identity links (user attributes); MongoDB holds team/KB assignments, ASP policies, app metadata |
| ⑦ | Agents | GitHub / Jira / ArgoCD | Downstream API calls using brokered user tokens |
Authorization Enforcement Points
098 defines three enforcement zones, each with its own PDP:
| Zone | Enforcement Point | PDP | Traffic |
|---|---|---|---|
| UI | Next.js BFF (NextAuth middleware) | Keycloak Authorization Services | Admin UI API routes, page access |
| Slack / Webex | Bot backend middleware | Keycloak Authorization Services | Slack commands, Webex events |
| MCP / A2A / Agent | Agent Gateway (required) | AG built-in (CEL policy) | MCP tool calls, A2A tasks, agent dispatch |
All three zones enforce the same 098 permission matrix (FR-014). Default deny applies everywhere (FR-002).
Sequence Diagram 1: Slack Identity Linking (FR-025)
One-time flow to establish the slack_user_id ↔ keycloak_sub mapping. The mapping is stored as a Keycloak user attribute — the bot has no MongoDB dependency.
Sequence Diagram 2: Authorized Request Flow
Every subsequent request after identity linking. Shows OBO exchange, PDP check, and agent execution.
IdP Groups → Keycloak Roles Mapping (FR-010)
Enterprise IdP groups (Okta and Microsoft Entra ID / AD-backed groups) are mapped to CAIPE platform roles at token issuance time inside Keycloak — no runtime SCIM sync or directory lookups. Keycloak acts as a required OIDC broker that federates both IdPs.
Sequence Diagram 3: IdP Groups → Keycloak Roles (Runtime)
This diagram shows what happens at login time when a user authenticates through a federated IdP. It covers both the SAML path (Okta SAML, Entra SAML) and the OIDC path (Okta OIDC).
Keycloak Mapper Configuration (One-Time Admin Setup)
Three layers of mappers work together to transform IdP groups into JWT claims:
| Layer | Mapper Type | Keycloak Config | Purpose |
|---|---|---|---|
| 1. Import | Identity Provider Mapper | SAML: "Attribute Importer" — attribute name groups → user attribute idp_groups | Extracts groups from IdP assertion/token into Keycloak user profile |
OIDC: "Claim to User Attribute" — claim groups → user attribute idp_groups | |||
| 2. Map to Roles | Identity Provider Mapper | "Hardcoded Role" or "SAML Attribute IdP Role Mapper" — when groups contains platform-admin → assign KC realm role admin | Converts IdP group membership into Keycloak realm roles |
| Repeat per group → role mapping | |||
| 3. Emit in JWT | Client Protocol Mapper | "Group Membership" → token claim groups | Emits groups in JWT for downstream consumers |
"Realm Role" → token claim roles | Emits mapped roles in JWT | ||
"User Attribute" → token claim org | Emits tenant/org context in JWT |
IdP-Specific Federation Setup
| IdP | Protocol | Group Source | Keycloak Broker Config |
|---|---|---|---|
| Okta (SAML) | SAML 2.0 | SAML Assertion → Attribute Statement groups | Identity Provider → SAML → Import SAML attributes |
| Okta (OIDC) | OIDC | ID Token → groups claim (requires Okta "Groups claim" config in the Okta app) | Identity Provider → OIDC → Import OIDC claims |
| Microsoft Entra ID (SAML) | SAML 2.0 | SAML Assertion → http://schemas.microsoft.com/ws/2008/06/identity/claims/groups (GUIDs) or custom groups attribute | Identity Provider → SAML → Attribute Importer (map GUIDs or group names) |
| Microsoft Entra ID (OIDC) | OIDC | ID Token → groups claim (requires Entra "Group claims" config in App Registration → Token configuration) | Identity Provider → OIDC → Claim to User Attribute |
Entra ID note: By default Entra sends group Object IDs (GUIDs) in SAML/OIDC. To get human-readable names, configure "Emit groups as role claims" or use the
cloud_displayNamesource attribute in the enterprise app's SAML claims configuration.
Group → Role Mapping Table
| IdP Group | Keycloak Realm Role | Capabilities (098 matrix examples) |
|---|---|---|
platform-admin | admin | All protected capabilities |
team-a-eng | team_member(team-a) | Chat, invoke team-a tools, query team-a KBs |
kb-admins | kb_admin | Create/update/delete KBs, manage ingest |
team-b-ops | team_member(team-b) | Chat, invoke team-b tools, query team-b KBs |
| (no group) | (no role) | Default deny — no platform access (FR-002) |
Resulting JWT Claims (Example)
{
"sub": "a1b2c3d4-...",
"iss": "https://keycloak.caipe.example.com/realms/caipe",
"aud": "caipe-platform",
"groups": ["platform-admin", "team-a-eng"],
"roles": ["admin", "team_member(team-a)"],
"org": "acme-corp",
"scope": "openid profile caipe",
"exp": 1743900000
}
The CAIPE platform, Agent Gateway, and Keycloak PDP all consume these JWT claims directly — no callback to the IdP or Keycloak at authorization time.
Multi-Tenant Isolation (FR-020)
┌─────────────────────────────────┐
│ Tenant Boundary │
│ ┌───────────┐ ┌───────────┐ │
│ │ Org A │ │ Org B │ │
│ │ │ │ │ │
│ │ Users A │ │ Users B │ │
│ │ Agents A │ │ Agents B │ │
│ │ Tools A │ │ Tools B │ │
│ │ KBs A │ │ KBs B │ │
│ │ │ │ │ │
│ │ JWT.org=A │ │ JWT.org=B │ │
│ └───────────┘ └───────────┘ │
│ │
│ PDP + AG enforce: principal │
│ in org A CANNOT access org B │
│ resources (FR-020) │
└─────────────────────────────────┘
Slack Identity Linking (FR-025)
The identity linking flow establishes the slack_user_id ↔ keycloak_sub mapping required before any OBO exchange. The mapping is stored as a custom Keycloak user attribute — the Slack bot has no MongoDB dependency.
Storage mechanism
| Aspect | Detail |
|---|---|
| Where | Keycloak user profile — custom attribute slack_user_id |
| Write (linking) | Bot calls Keycloak Admin API to set slack_user_id on the authenticated user |
| Read (lookup) | Bot calls Keycloak Admin API to find user by attribute slack_user_id = X → returns keycloak_sub |
| Bot dependencies | Keycloak only (Admin API + OIDC); no MongoDB on the Slack path |
Flow
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Slack │ │ Slack Bot │ │ Keycloak │ │ Enterprise │
│ User │ │ Backend │ │ (broker) │ │ IdP (Okta) │
└────┬─────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ 1. First │ │ │
│ command ──────▶│ │ │
│ │ 2. Admin API: │ │
│ │ find user by │ │
│ │ slack_user_id=X ──▶│ │
│ │◀── Not found ──────│ │
│ │ │ │
│◀─── 3. "Link ──│ │ │
│ account" URL │ │ │
│ (single-use, │ │ │
│ time-bounded) │ │ │
│ │ │ │
│── 4. Click ────────────────────────▶│ │
│ URL │ │── 5. Federate ──▶│
│ │ │◀── 6. SAML ──────│
│◀──── 7. Auth ───────────────────────│ │
│ success │ │ │
│ │◀── 8. Callback ────│ │
│ │ (keycloak_sub) │ │
│ │ │ │
│ │ 9. Admin API: set │ │
│ │ slack_user_id=X on │ │
│ │ keycloak_sub ─────▶│ │
│ │◀── OK ─────────────│ │
│◀─ 10. "Linked!" │ │ │
│ │ │ │
│ 11. Subsequent │ │ │
│ commands ─────▶│ 12. Admin API: │ │
│ │ find slack_user_id │ │
│ │ → keycloak_sub ───▶│ │
│ │◀── keycloak_sub ───│ │
│ │ 13. OBO exchange │ │
│ │ (RFC 8693) ───────▶│ │
│ │◀── JWT ────────────│ │
Security constraints: Linking URL is single-use, time-bounded (short TTL), HTTPS-only. Unlinked users are denied all RBAC-protected operations.
RBAC Configuration Store (FR-023)
┌───────────────────────────────────────────────────────┐
│ CAIPE Admin UI (FR-024) │
│ Administrators manage RBAC here │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Roles & Access Tab (US6) │ │
│ │ • Create/delete custom realm roles │ │
│ │ • Map IdP groups → realm roles │ │
│ │ • Assign roles to teams │ │
│ └─────────────────────────────────────────────────┘ │
└──────────┬──────────────────────────┬─────────────────┘
│ │
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ Keycloak │ │ MongoDB │
│ (Admin REST API) │ │ │
│ │ │ │
│ • Resources │ │ • Team/KB ownership │
│ (components) │ │ assignments │
│ • Scopes │ │ • Custom RAG tool │
│ (capabilities) │ │ bindings │
│ • Policies │ │ • App metadata │
│ (role-based) │ │ • ASP tool policies │
│ • Realm Roles │ │ • Team keycloak_ │
│ (CRUD via UI) │ │ roles assignments │
│ • IdP Mappers │ │ │
│ (group→role, UI) │ │ │
│ • Permissions │ │ │
│ • User attributes │ │ │
│ (slack_user_id) │ │ │
│ (FR-025) │ │ │
│ │ │ │
│ PDP for UI/Slack │ │ Operational state │
└──────────────────────┘ └──────────────────────┘
Admin UI → Keycloak Admin API Flow (FR-024, US6)
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Admin UI │ │ BFF API Routes │ │ Keycloak Admin │
│ RolesAccessTab │──▶│ /api/admin/ │──▶│ REST API │
│ │ │ roles, │ │ │
│ CreateRole │ │ role-mappings, │ │ client_creds │
│ Dialog │ │ teams/:id/roles │ │ grant auth │
│ │ │ │ │ │
│ GroupMapping │ │ requireAdmin() │ │ realm-management│
│ Dialog │ │ session check │ │ service account │
└──────────────────┘ └──────────────────┘ └──────────────────┘
OBO Delegation Chain (FR-018, FR-019)
The multi-hop delegation chain ensures the originating user is always the effective principal:
User ──▶ Slack Bot ──▶ Supervisor ──▶ Agent ──▶ MCP Tool
│ │ │ │ │
│ OBO exchange Forwards Forwards AG checks
│ (RFC 8693) user JWT user JWT JWT.sub=user
│ │ │ │ │
└─── sub=user ──────────────────────────────────────┘
act=bot
scope=user's entitlements (not bot's)
groups=[user's groups]
org=user's org
Effective permissions = intersection of:
• User's entitlements (098 matrix)
• Bot service account's scope ceiling
• Component's matrix row (FR-008)
PDP Architecture (FR-022)
Keycloak is required (Session 2026-04-03). Enterprise IdPs (Okta, Entra, SAML) federate into Keycloak via identity brokering.
| Path | PDP | How |
|---|---|---|
| UI / Slack / Webex | Keycloak Authorization Services | UMA / resource-based permissions; 098 matrix modeled as KC resources, scopes, policies |
| MCP / A2A / Agent | Agent Gateway | CEL policy; JWT issued by Keycloak |
Keycloak Authorization Services:
- Consume JWT
groups,roles,scope,orgclaims (FR-010) - 098 permission matrix modeled as Keycloak resources (components), scopes (capabilities), and policies (role-based)
- Return allow/deny with audit-grade detail (FR-005)
- Target sub-5ms decision latency
- Admin manages policies via Keycloak Admin Console or CAIPE Admin UI (which calls Keycloak Admin API)
Map RAG RBAC to Keycloak + Per-KB Access Control Architecture Overview
The RAG server is integrated into the Keycloak RBAC system with defense-in-depth enforcement. The BFF performs coarse Keycloak AuthZ checks; the RAG server validates the JWT directly and enforces per-KB access control. This section documents the architecture for FR-026 (Keycloak JWT integration) and FR-027 (per-KB access control).
Dual-Layer Enforcement Flow
Keycloak Realm Role to RAG Server Role Mapping (FR-026)
The RAG server maps Keycloak realm roles from the JWT roles claim to its internal role hierarchy. When the roles claim is present, Keycloak role mapping takes precedence. When absent, the existing group-based assignment (RBAC_*_GROUPS) is used as fallback.
| Keycloak Realm Role | RAG Server Role | Permissions | KB Access |
|---|---|---|---|
admin | admin | read, ingest, delete | All KBs (global override) |
kb_admin | ingestonly | read, ingest | All KBs (global override) |
team_member | readonly | read | Team-owned KBs only |
chat_user | readonly | read | Per-KB roles or team-owned KBs |
kb_reader:<kb-id> | readonly (scoped) | read | Specified KB only |
kb_reader:* | readonly (all) | read | All KBs (wildcard) |
kb_ingestor:<kb-id> | ingestonly (scoped) | read, ingest | Specified KB only |
kb_ingestor:* | ingestonly (all) | read, ingest | All KBs (wildcard) |
kb_admin:<kb-id> | admin (scoped) | read, ingest, delete | Specified KB only |
| (no matching role) | anonymous | (none) | No KBs |
Per-KB Access Resolution (FR-027)
Effective KB access is the union of Keycloak per-KB roles and team ownership. Global roles override per-KB restrictions.
Query-Time KB Filtering
The /v1/query endpoint injects a datasource_id filter into vector DB queries based on the user's accessible KB list. This is server-side enforced and transparent to the caller — the API consumer does not need to know which KBs they can access.
User calls POST /v1/query { "query": "how do I deploy?", "filters": {} }
┌─────────────────────────────────────────────────┐
│ RAG Server /v1/query handler │
│ │
│ 1. Validate JWT → UserContext (role, kb_perms) │
│ 2. require_role(Role.READONLY) ✓ │
│ 3. get_accessible_kb_ids(user_context) │
│ → ["kb-team-a", "kb-platform"] │
│ 4. inject_kb_filter(query, accessible_kbs) │
│ → filters.datasource_id IN [...] │
│ 5. VectorDBQueryService.query(filtered_request) │
│ → results from kb-team-a + kb-platform only │
└─────────────────────────────────────────────────┘
Defense-in-Depth Enforcement Layers
Four layers of authorization checks protect KB operations:
| Layer | Check | PDP | Scope | Failure Mode |
|---|---|---|---|---|
1. BFF /api/rag/kb/* | requireRbacPermission("rag", "kb.query") | Keycloak AuthZ | Coarse capability (can user do KB operations at all?) | 401/403 to UI |
| 2. RAG global role | require_role(Role.READONLY) via JWT → Keycloak role mapper | RAG server (JWT) | Global role check (is user authenticated with sufficient role?) | 401/403 from RAG |
| 3. RAG per-KB access | require_kb_access(kb_id, scope) | RAG server (JWT + MongoDB) | Fine-grained per-KB (can user access THIS specific KB?) | 403 from RAG |
| 4. RAG query filter | inject_kb_filter() in /v1/query | RAG server (JWT + MongoDB) | Query-time row filtering (restrict results to accessible KBs) | Empty results / 503 |
If any layer denies, the operation is denied. If MongoDB is unavailable for team ownership lookup, the system fails closed (deny).
Dynamic Agent RBAC Architecture (FR-028, FR-029, FR-030)
Dynamic agents are governed by the same Keycloak RBAC model as KBs and tools. This section documents the three-layer authorization model, CEL as the universal policy engine, and deepagent MCP routing through Agent Gateway.
Three-Layer Enforcement Flow
Dynamic Agent Role Mapping Table
| Keycloak Realm Role | Scopes Granted | Agent Access |
|---|---|---|
admin | view, invoke, configure, delete | All agents (global override) |
agent_admin:<agent-id> | view, invoke, configure, delete | Specified agent only |
agent_admin:* | view, invoke, configure, delete | All agents (wildcard) |
agent_user:<agent-id> | view, invoke | Specified agent only |
agent_user:* | view, invoke | All agents (wildcard) |
team_member(team-x) | view, invoke (team agents) | Agents with visibility: team + shared_with_teams includes team-x |
| (owner) | view, invoke, configure, delete | Own agents (owner_id match) |
| (no matching role) | (none) | Only visibility: global agents |
Per-Agent Access Resolution
Effective agent access is the union of three sources: per-agent Keycloak roles, MongoDB visibility, and ownership. CEL evaluates all three at runtime.
CEL as Universal Policy Engine (FR-029)
CEL is mandated at all four enforcement points. Each service embeds a CEL evaluator library with a shared context schema.
┌──────────────────────────────────────────────────────────────┐
│ CEL Context Schema │
│ │
│ user.roles : ["admin", "agent_user:agent-123", ...] │
│ user.teams : ["team-a", "team-b"] │
│ user.email : "user@corp.com" │
│ resource.id : "agent-123" | "kb-team-a" | ... │
│ resource.type : "dynamic_agent" | "kb" | "rag_tool" │
│ resource.visibility : "private" | "team" | "global" │
│ resource.owner_id : "owner@corp.com" │
│ resource.shared_with_teams : ["team-a"] │
│ action : "view" | "invoke" | "configure" | ... │
└──────────────────────────────────────────────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐
│ Agent │ │ RAG Server │ │ Dynamic │ │ BFF │
│ Gateway │ │ (Python) │ │ Agents │ │ (TS) │
│ │ │ │ │ (Python) │ │ │
│ CEL built-in │ │ cel-python │ │ cel-python │ │ cel-js │
│ (Rust) │ │ │ │ │ │ │
│ │ │ Per-KB │ │ Per-agent │ │ RBAC │
│ MCP/A2A/ │ │ access │ │ access │ │ middleware│
│ agent policy │ │ (FR-027) │ │ (FR-028) │ │ checks │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────┘
Example CEL expressions (configurable, not hardcoded):
// Dynamic agent view access
user.roles.exists(r, r == "admin")
|| user.roles.exists(r, r == "agent_user:" + resource.id)
|| user.roles.exists(r, r == "agent_user:*")
|| resource.visibility == "global"
|| (resource.visibility == "team"
&& resource.shared_with_teams.exists(t, t in user.teams))
|| resource.owner_id == user.email
// KB read access (same pattern)
user.roles.exists(r, r == "admin" || r == "kb_admin")
|| user.roles.exists(r, r == "kb_reader:" + resource.id)
|| user.roles.exists(r, r == "kb_reader:*")
|| resource.team_owned_by.exists(t, t in user.teams)
Deepagent MCP Routing (FR-030)
Slack Channel-to-Team RBAC (FR-031, FR-032)
Slack channels act as team selectors — providing context for which team's resources (KBs, agents, tools) are in scope. The channel does not grant additional permissions; the user's Keycloak roles are the sole authority.
Slack Bot RBAC Flow with Channel Context
Slack Bot Data Sources
┌─────────────────────────────────────────────────────┐
│ Slack Bot Runtime │
│ │
│ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ Keycloak │ │ MongoDB │ │
│ │ │ │ │ │
│ │ • Identity │ │ • Channel-to-team │ │
│ │ linking │ │ mappings (FR-031) │ │
│ │ (FR-025) │ │ │ │
│ │ • OBO token │ │ • Operational metrics │ │
│ │ exchange │ │ (last interaction, │ │
│ │ (FR-018) │ │ OBO success/fail) │ │
│ │ • AuthZ PDP │ │ │ │
│ │ (FR-022) │ │ Cached in bot memory │ │
│ │ │ │ with 60s TTL │ │
│ └──────────────┘ └──────────────────────────┘ │
│ │
│ Identity & Auth ←── Keycloak (source of truth) │
│ Team Context ←── MongoDB (channel mappings) │
└─────────────────────────────────────────────────────┘
Admin UI Slack Management Dashboard (FR-032)
Component Summary
| Component | Role | Required? | Authorization |
|---|---|---|---|
| Slack / Webex | User-facing entry (at least one) | At least one channel | Bot validates identity + PDP check |
| CAIPE Admin UI | Admin web interface | Yes | NextAuth session + PDP check |
| Slack Bot / Webex Bot Backend | Event handling, identity resolution (via Keycloak user attributes), OBO exchange | Yes | PDP for capability checks; no MongoDB dependency |
| Keycloak (required) | OIDC broker, token issuance, groups→roles mapping, OBO, Authorization Services (PDP), Slack identity link storage (user attributes) | Required | Source of JWT claims + PDP for UI/Slack + identity link store |
| Enterprise IdP | SSO (Okta SAML, Entra AD); federated into Keycloak | Optional | Federation source |
| Agent Gateway | MCP/A2A gateway, JWT validation, CEL policy | Required | PDP for agent traffic |
| Supervisor / Orchestrator | A2A server, agent routing | Yes | Carries forwarded identity |
| Domain Agents | GitHub, Jira, ArgoCD, etc. | Yes | OBO tokens for downstream |
| MCP Servers | Tool invocation | Yes | AG-gated access |
| RAG Server | KBs, datasources | Yes | PDP-gated admin; AG-gated queries; CEL per-KB access (FR-027) |
| Dynamic Agents | User-created/runtime agents, deepagent LangGraph | Yes | Three-layer RBAC: Keycloak resource + per-agent roles + MongoDB visibility + CEL (FR-028); MCP calls via AG (FR-030) |
| Slack Bot | Slack commands, identity linking, channel-team scoping | Yes | Identity linking via Keycloak (FR-025); OBO exchange (FR-018); channel-to-team mapping from MongoDB with 60s cache (FR-031); AuthZ via Keycloak PDP (FR-022); Admin UI dashboard (FR-032) |
| MongoDB | Users, policies, permission matrix, team/KB config (no Slack identity links — those are in Keycloak) | Yes | Data store for PDP + Admin UI |
Fail-Closed Behavior
| Failure | Impact | Behavior |
|---|---|---|
| Agent Gateway down | MCP/A2A/agent traffic | Denied (fail closed). Slack and Admin UI unaffected. |
| Keycloak down | Token issuance, login, UI/Slack authz | No new sessions; existing valid JWTs may continue until expiry; authz checks denied (fail closed). |
| MongoDB unavailable | Matrix/config reads | PDP returns deny (fail closed). |
FR-038: Team-Based KB RBAC + Agent Gateway MCP Routing
Overview
FR-038 introduces team-based KB access control with Agent Gateway MCP routing, OBO token propagation, and per-session auth-aware supervisor tools.
Architecture Diagram
┌────────────────────────────────────────────────────────────────────┐
│ CAIPE UI (Next.js) │
│ ┌────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ KB Browser │ │ Admin Teams │ │ Agent Chat (A2A SDK) │ │
│ │ (IngestView)│ │ (KB Assign) │ │ accessToken in Bearer │ │
│ └─────┬──────┘ └──────┬───────┘ └────────────┬─────────────┘ │
│ │ │ │ │
└────────┼────────────────┼────────────────────────┼──────────────────┘
│ REST │ REST │ A2A JSON-RPC
▼ ▼ ▼
┌────────────────────────────────────────────────────────────────────┐
│ BFF API Routes (Next.js) │
│ ┌───────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │
│ │ /api/rag/kb/* │ │ /api/admin/teams │ │ /api/a2a/… │ │
│ │ adds X-Team-Id│ │ /[id]/kb-assign │ │ forwards Bearer │ │
│ │ header │ │ CRUD on MongoDB │ │ to supervisor │ │
│ └───────┬───────┘ └──────┬───────────┘ └─────────┬────────────┘ │
│ │ │ │ │
│ ▼ ▼ │ │
│ ┌───────────┐ ┌──────────────┐ │ │
│ │ RAG Server│ │ MongoDB │ │ │
│ │ REST API │ │ team_kb_ │ │ │
│ │ (direct) │ │ ownership │ │ │
│ └───────────┘ └──────────────┘ │ │
└───────────────────────────────────────────────────┼───────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────┐
│ Supervisor (A2A Server) │
│ ┌─────────────┐ ┌────────────────────────────┐ │
│ │ Extract user │ │ OBO Token Exchange │ │
│ │ Bearer from │──│ POST /realms/…/protocol/ │ │
│ │ HTTP request │ │ openid-connect/token │ │
│ │ │ │ grant_type=token-exchange │ │
│ └──────────────┘ │ subject_token=user_jwt │ │
│ │ → OBO JWT (sub=user,act=svc) │ │
│ └──────────┬─────────────────┘ │
│ │ │
│ ┌────────────────────────────▼────────────────────────────────┐ │
│ │ Auth-Aware Proxy Tools (wrap_rag_tools_with_auth) │ │
│ │ ┌──────────────────────┐ │ │
│ │ │ Original RAG Tool │ Reads obo_token from │ │
│ │ │ (from compiled graph)│ RunnableConfig.configurable │ │
│ │ │ name + schema kept │ ──► per-invocation MCP client │ │
│ │ └──────────────────────┘ with Bearer auth │ │
│ └─────────────────────────────────────┬───────────────────────┘ │
│ │ │
└────────────────────────────────────────┼───────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────┐
│ Agent Gateway (AG) │
│ ┌──────────────┐ ┌────────────────┐ ┌────────────────────────┐ │
│ │ JWT Validate │ │ CEL Policy │ │ Target: rag │ │
│ │ (Keycloak │ │ Evaluation │ │ mcp: │ │
│ │ JWKS) │ │ (tool-level │ │ host: rag_server: │ │
│ │ │ │ authz) │ │ 9446/mcp │ │
│ └──────┬───────┘ └───────┬────────┘ └─────────┬──────────────┘ │
│ │ │ │ │
│ └──────────────────┴──────────────────────┘ │
│ │ Authorized │
│ ▼ │
└────────────────────────────┼───────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────┐
│ RAG Server │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ rbac.py: │ │
│ │ - Extract team_id from JWT roles or X-Team-Id header │ │
│ │ - Query MongoDB team_kb_ownership for allowed datasources │ │
│ │ - Filter /v1/datasources and MCP tool responses │ │
│ │ - Fail closed: if MongoDB unreachable → empty results │ │
│ └──────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────┐
│ Dynamic Agents │
│ ┌──────────────┐ ┌─────────────────────────────────────────┐ │
│ │ AgentRuntime │ │ MCP Client (per-session) │ │
│ │ auth_bearer = │──│ agent_gateway_url = AGENT_GATEWAY_URL │ │
│ │ user OBO JWT │ │ headers: Authorization: Bearer <obo> │ │
│ └──────────────┘ └──────────────────┬──────────────────────┘ │
│ │ │
│ Sub-agents inherit auth_bearer │ │
│ and agent_gateway_url │ │
└───────────────────────────────────────┼────────────────────────────┘
│
▼
Agent Gateway
(same as above)
Data Flow: Team-Scoped KB Query via Supervisor
- User sends chat → UI attaches
accessTokenas Bearer header - BFF forwards Bearer to supervisor A2A endpoint
- Supervisor extracts user JWT from request, performs OBO token exchange with Keycloak (RFC 8693):
grant_type=urn:ietf:params:oauth:grant-type:token-exchange,subject_token=<user_jwt>→ receives OBO JWT withsub=user, act.sub=caipe-platform - Auth-aware proxy tool is invoked by LangGraph; it reads
obo_tokenfromRunnableConfig.configurable, creates an ephemeral MCP client withAuthorization: Bearer <obo_token>, connects to AG - Agent Gateway validates the OBO JWT via Keycloak JWKS, evaluates CEL tool-level policies, forwards the MCP request to RAG server target
- RAG server extracts team membership from JWT roles (
team_member(<id>)), queriesteam_kb_ownershipin MongoDB for allowed datasource IDs, filters results, returns only team-authorized data
Data Flow: Team-Scoped KB Ingest via UI
- User navigates to KB → IngestView; UI calls
GET /api/rag/kb/v1/datasources - BFF proxy adds
X-Team-Idheader (from session JWT roles) and proxies to RAG server - RAG server checks
team_kb_ownership— if user's team hasingestoradminon the target datasource, allow; otherwise deny - UI hides ingest/delete buttons for KBs where the user's team lacks matching permissions; shows team-ownership badges
Fallback Behavior
| Condition | Behavior |
|---|---|
AGENT_GATEWAY_URL unset | Supervisor + dynamic agents connect directly to MCP servers (no AG, no OBO) |
| OBO exchange fails | Supervisor falls back to service-account token (reduced access) |
MongoDB team_kb_ownership unreachable | RAG server returns empty results (fail-closed) |
| AG down | MCP calls denied; UI REST path unaffected |
FR-038h: KB UI Team Assignment Architecture
The Knowledge Base UI provides inline team access management through a reusable
KbTeamAccessPanel React component that operates in two modes (compact and full),
plus an optional team selector in the ingest form.
Component Architecture
┌─────────────────────────────────────────────────────────────────────────┐
│ IngestView.tsx │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Ingest Form │ │
│ │ ┌────────────┐ ┌─────────────┐ ┌────────────────┐ │ │
│ │ │ URL input │ │ Share with: │ │ Permission: │ │ │
│ │ │ │ │ <select> │ │ <select> │ │ │
│ │ │ │ │ (optional) │ │ read/ingest/ │ │ │
│ │ │ │ │ │ │ admin │ │ │
│ │ └────────────┘ └─────────────┘ └────────────────┘ │ │
│ │ │ │
│ │ On success: POST ingest → PUT /api/admin/teams/{id}/ │ │
│ │ kb-assignments (assign new datasource) │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Datasource Row │ │
│ │ ┌───────────┐ ┌───────┐ ┌──────────────────────┐ ┌──────┐ │ │
│ │ │ Name │ │Badges │ │KbTeamAccessPanel │ │Type │ │ │
│ │ │ │ │(teams)│ │mode="compact" │ │badge │ │ │
│ │ │ │ │ │ │(Users icon→popover) │ │ │ │ │
│ │ └───────────┘ └───────┘ └──────────────────────┘ └──────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Expanded Datasource Detail │ │
│ │ ┌────────────────────────────────────────────────────────┐ │ │
│ │ │ KbTeamAccessPanel mode="full" │ │ │
│ │ │ ┌────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ Team Access │ │ │ │
│ │ │ │ ┌────────────┬──────────┬────────┐ │ │ │ │
│ │ │ │ │ Team Name │ Perm │ Remove │ │ │ │ │
│ │ │ │ ├────────────┼──────────┼────────┤ │ │ │ │
│ │ │ │ │ Platform │ Ingest ▼ │ 🗑 │ │ │ │ │
│ │ │ │ │ DataSci │ Read ▼ │ 🗑 │ │ │ │ │
│ │ │ │ └────────────┴──────────┴────────┘ │ │ │ │
│ │ │ │ ┌──────────────┬──────────┬──────┐ │ │ │ │
│ │ │ │ │ Add team...▼ │ Perm ▼ │ + │ │ │ │ │
│ │ │ │ └──────────────┴──────────┴──────┘ │ │ │ │
│ │ │ └────────────────────────────────────────────────────┘ │ │ │
│ │ └────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Data Flow: KB UI Team Assignment
User clicks Share icon (compact) or views expanded detail (full)
│
▼
KbTeamAccessPanel
│
├──► GET /api/admin/teams → list all teams
│
├──► GET /api/admin/teams/{id}/kb-assignments (per team)
│ → build: which teams have this datasource assigned?
│
├──► User adds team:
│ GET /api/admin/teams/{id}/kb-assignments (current state)
│ PUT /api/admin/teams/{id}/kb-assignments (append datasource)
│ → calls onUpdate() → reloadTeamKb()
│
├──► User removes team:
│ DELETE /api/admin/teams/{id}/kb-assignments?datasource_id=...
│ → calls onUpdate() → reloadTeamKb()
│
└──► User changes permission:
GET /api/admin/teams/{id}/kb-assignments (current state)
PUT /api/admin/teams/{id}/kb-assignments (update kb_permissions)
→ calls onUpdate() → reloadTeamKb()
Data Flow: Post-Ingest Team Assignment
User fills ingest form + selects team + permission
│
▼
handleIngest()
│
├──► POST /api/rag/kb/v1/ingest (create datasource + job)
│ → returns { datasource_id, job_id }
│
└──► If ingestTeamId is set:
GET /api/admin/teams/{id}/kb-assignments (current state)
PUT /api/admin/teams/{id}/kb-assignments (append new datasource_id)
→ reloadTeamKb()
New Files
| File | Purpose |
|---|---|
ui/src/components/rag/KbTeamAccessPanel.tsx | Reusable panel (compact popover + full inline) for managing team-KB assignments per datasource |
Modified Files
| File | Changes |
|---|---|
ui/src/components/rag/IngestView.tsx | Import KbTeamAccessPanel; add compact Share button per row; add full panel in detail; add team/permission selectors in ingest form; post-ingest team assignment |
ui/src/hooks/useTeamKbOwnership.ts | Already exports reload (used as reloadTeamKb) |
FR-038d: AG End-to-End + RAG MCP RBAC Enforcement Architecture
Problem
Team-based KB scoping was enforced only on the UI REST path (BFF sets X-Team-Id, RAG server calls inject_kb_filter). The Slack/supervisor MCP path bypassed all RBAC because:
AGENT_GATEWAY_URLwas not set, so auth-aware proxy tools were not activatedKEYCLOAK_SUPERVISOR_CLIENT_SECRETwas not mapped, so OBO exchange could not workMCPAuthMiddlewarevalidated auth but discardedUserContext- MCP tool functions called
vector_db_query_service.query()with no team filtering
MCP RBAC Data Flow (After Fix)
┌──────────┐ JWT ┌──────────────┐ OBO Token ┌───────────────┐
│ Slack │ ──────→ │ Supervisor │ ───────────→ │ Agent Gateway │
│ User │ │ (caipe-sup) │ │ (AG) │
└──────────┘ └──────┬───────┘ └──────┬────────┘
│ │
wraps tools via validates JWT,
auth_mcp_tools.py applies CEL,
(OBO exchange) proxies to RAG
│ │
└────────────────────────────────┘
│
▼
┌───────────────────────────┐
│ RAG Server (/mcp) │
│ │
│ MCPAuthMiddleware │
│ ├─ validate Bearer JWT │
│ ├─ build UserContext │
│ └─ set contextvars │
│ │
│ MCP Tool (search, etc.) │
│ ├─ read UserContext │
│ ├─ extract team_id │
│ ├─ get_accessible_kb_ids│
│ └─ filter query results │
└───────────────────────────┘
Changes Made
docker-compose.dev.yaml
- Set
AGENT_GATEWAY_URLdefault tohttp://agentgateway:4000for supervisor and dynamic-agents - Map
KEYCLOAK_SUPERVISOR_CLIENT_IDandKEYCLOAK_SUPERVISOR_CLIENT_SECRETfor OBO exchange
ai_platform_engineering/knowledge_bases/rag/server/src/server/restapi.py
- Added
mcp_user_context_var: ContextVar[Optional[UserContext]] - Modified
MCPAuthMiddleware.dispatch()to storeUserContextonrequest.state.userand set the context variable for both JWT-authenticated and trusted-network requests - Context variable is properly reset after each request using
try/finally
ai_platform_engineering/knowledge_bases/rag/server/src/server/tools.py
- Added
_get_mcp_user_context(): readsUserContextfrommcp_user_context_var - Added
_extract_team_id(): parsesteam_member(<id>)from realm roles - Added
_resolve_accessible_kb_ids(): resolves accessible KB IDs viaget_accessible_kb_ids(), returns None for unrestricted access - Modified
search(): applies datasource_id filter before querying - Modified
fetch_document(): adds datasource_id filter to document fetch - Modified
list_datasources_and_entity_types(): filters returned datasource list - Modified
_make_search_fn/_execute(): intersects per-search datasource_ids with RBAC-accessible IDs
FR-039: AG Dynamic CEL Policy Management Architecture
Overview
Agent Gateway reads CEL authorization rules from config.yaml (file-watched for hot-reload). The Admin UI stores policies in MongoDB. A config-bridge sidecar synchronizes policies from MongoDB to AG's config file, enabling zero-downtime policy updates from the Admin UI.
Component Architecture
Hot-Reload Flow
CEL Validation Strategy
Two-layer validation prevents invalid policies from reaching Agent Gateway:
-
Client-side (live): The
AgMcpPoliciesEditorcomponent usescel-js(via@/lib/rbac/cel-evaluator) to validate expressions as the admin types (debounced 300ms). A mock AG context withjwt.realm_access.roles,mcp.tool.name, andrequest.headersis used for dry-run evaluation, showing whether the expression would allow or deny the mock request. -
Server-side (on save): The BFF route (
/api/rbac/ag-policiesPUT) runsevalCel(expression, agDryContext)before upserting to MongoDB. Invalid expressions return HTTP 400 with the parse error.
MongoDB Collections
| Collection | Purpose | Key Fields |
|---|---|---|
ag_mcp_policies | CEL rules per backend/tool pattern | backend_id, tool_pattern, expression, enabled |
ag_mcp_backends | MCP upstream targets | id, upstream_url, description, enabled |
ag_sync_state | Generation counter for sync tracking | policy_generation, bridge_generation, bridge_last_sync, bridge_error |
Deployment Models
Docker dev (docker-compose.dev.yaml):
ag-config-bridgecontainer sharesag_confignamed volume withagentgateway- Bridge writes to
/etc/agentgateway/config.yaml; AG reads from the same path - Bridge polls MongoDB every 5 seconds (configurable via
AG_POLL_INTERVAL)
Kubernetes prod (future):
- Option A: Sidecar in AG pod +
emptyDirshared volume - Option B: If kgateway is adopted, migrate to
AgentgatewayPolicyCRDs via K8s operator
Files Changed
| File | Change |
|---|---|
deploy/agentgateway/config.yaml.j2 | New — Jinja2 template for AG config |
deploy/agentgateway/config-bridge.py | New — Python sidecar with MongoDB poll + template render |
deploy/agentgateway/Dockerfile.config-bridge | New — Container image for bridge |
deploy/agentgateway/requirements.txt | New — pymongo + jinja2 |
ui/src/app/api/rbac/ag-policies/route.ts | New — BFF CRUD with CEL validation |
ui/src/app/api/rbac/ag-sync-status/route.ts | New — Sync status endpoint |
ui/src/components/admin/AgMcpPoliciesEditor.tsx | New — Admin UI editor with validation + hot-reload |
ui/src/lib/rbac/types.ts | Added AgMcpPolicy, AgMcpBackend, AgSyncState types |
ui/src/lib/mongodb.ts | Added indexes for new collections |
ui/src/app/api/rbac/admin-tab-gates/route.ts | Added ag_policies tab gate |
ui/src/app/(app)/admin/page.tsx | Added AG MCP Policies tab to Security & Policy category |
docker-compose.dev.yaml | Added ag-config-bridge service + ag_config shared volume |
Related Documents
- spec.md — Feature specification (098)
- 093 architecture — Historical architecture (superseded)
- 093 research index — Policy engine comparison, AG/Keycloak research
- Agent Gateway — Upstream project
- AG Keycloak tutorial — OIDC integration reference