Tenants
Tenant identity is derived at the gateway. External clients should not send tenant headers and expect them to be trusted.
How Tenant IDs Flow
- The user authenticates through Keycloak or another trusted issuer.
- The gateway strips inbound identity headers.
- The gateway reads JWT claim
tenant. - If
tenantis absent, it falls back to JWTsub. - The gateway sets
X-Tenant-IDfor downstream services. - Services scope memory, knowledge, audit, sessions, and guardrails to that tenant.
To use organization-style tenants, add a Keycloak mapper that emits a stable tenant claim.
Development Mode
When gateway auth is disabled, TenantExtractor defaults missing tenant/user values to default and anonymous. That is useful for tests, but it is not the production trust model.
Storage Boundaries
| Area | Isolation |
|---|---|
| Sessions | Redis keys include tenant/session context. |
| Memory | Qdrant and Mem0 scopes include tenant and user. |
| Knowledge | Tenant plus owner/audience/role visibility policy. |
| Wiki | Tenant-owned pages with visibility metadata. |
| Audit | Tenant-scoped audit chain and turn envelopes. |
| Guardrails | Tenant and agent policy overlays. |
Admin Roles
| Role | Access |
|---|---|
tenant_admin | Tenant-scoped admin operations when X-Tenant-ID matches the requested tenant. |
platform_admin | Cross-tenant admin operations. |
admin | Legacy broad admin role. |
The development realm does not seed the split roles by default. Add them in Keycloak for production tenancy.
Validate Isolation
Use authenticated users whose tokens map to different tenant claims. Through the gateway, do not pass manual X-Tenant-ID as the source of truth.
curl "http://localhost:8080/v1/admin/audit?tenant_id=acme&limit=20" \
-H "Authorization: Bearer $ACME_TENANT_ADMIN_TOKEN"
A tenant_admin for another tenant should receive 403. A platform_admin can list across tenants.
Current Gaps
- There is no tenant create/delete API. Tenants appear when authenticated traffic first uses a tenant ID.
- Realm import seeds
adminanduser; split admin roles must be added by operators. - Tenant deletion is manual and must cover Qdrant, MinIO, Redis, PostgreSQL, and audit retention policy.