feat(rbac): introduce Tenant RBAC Guide documentation
- Added comprehensive documentation for the role-based access control (RBAC) system within tenants, detailing the purpose, role matrix, enforcement mechanisms, and configuration options. - Explained the implications of enabling RBAC, including the default settings and how to audit role assignments before activation. - Included schema references for the `tenant_members` and `audit_logs` tables to assist developers in understanding the underlying data structure.
This commit is contained in:
+351
@@ -0,0 +1,351 @@
|
||||
# Tenant RBAC Guide
|
||||
|
||||
How WeKnora enforces who-can-do-what inside a tenant, how to roll the
|
||||
feature out without breaking existing deployments, and how to audit
|
||||
the system once it is on.
|
||||
|
||||
> Status: shipped behind a feature flag (`tenant.enable_rbac`,
|
||||
> default `false`). Schema and `tenant_members` rows are populated
|
||||
> on every install; enforcement is opt-in.
|
||||
|
||||
## Why this exists
|
||||
|
||||
Before #1303 every authenticated user with `X-API-Key` or a JWT was
|
||||
effectively an Admin in their tenant. That's fine for a single-user
|
||||
self-host, but as soon as a tenant has more than one human (e.g. a
|
||||
small team sharing a knowledge base) you need to draw lines around:
|
||||
|
||||
- who may delete a knowledge base or revoke an API key (Admins);
|
||||
- who may upload documents and edit their own KB (Contributors);
|
||||
- who may only read and ask questions (Viewers).
|
||||
|
||||
RBAC layers a **per-tenant role matrix** on top of the existing JWT /
|
||||
API-key auth so all three states are first-class.
|
||||
|
||||
## The role matrix
|
||||
|
||||
Every tenant member has exactly one role, stored in `tenant_members.role`:
|
||||
|
||||
| Role | Typical use | Notable powers |
|
||||
|---------------|----------------------------------------------|----------------|
|
||||
| `viewer` | Read-only consumer (chat, search, browse). | None — reads only. |
|
||||
| `contributor` | Upload + edit **own** KBs / agents. | Can mutate resources whose `creator_id` matches their user ID. Cannot touch other contributors' resources. |
|
||||
| `admin` | Tenant-wide operator. | Can mutate any resource in the tenant; manages members; configures shared infrastructure (Ollama, parser, storage, etc.). |
|
||||
| `owner` | Tenant founder. | Same as Admin, plus may delete the tenant and cannot be demoted by another Admin. Exactly one Owner per tenant after backfill. |
|
||||
|
||||
Higher roles inherit lower roles' permissions. The hierarchy is
|
||||
`viewer < contributor < admin < owner`.
|
||||
|
||||
### Special cases the auth layer still handles
|
||||
|
||||
- **Cross-tenant superusers** (`User.CanAccessAllTenants` + the
|
||||
`enable_cross_tenant_access` flag + `X-Tenant-ID` header) get an
|
||||
Admin-level pass into the target tenant without needing a row in
|
||||
`tenant_members`. Used by org-level operators who administer many
|
||||
tenants.
|
||||
- **API-key callers** (`X-API-Key` synthetic users) are pinned to
|
||||
Admin in the tenant the key belongs to. This preserves every
|
||||
scripted-integration use case except tenant deletion (which still
|
||||
requires Owner).
|
||||
- **Orphan tenants** (zero `tenant_members` rows — typically
|
||||
API-key-only tenants) auto-promote the first authenticating human
|
||||
to Owner. Prevents lock-out after a fresh install.
|
||||
|
||||
## How enforcement is gated
|
||||
|
||||
Two routes a request can take:
|
||||
|
||||
```text
|
||||
┌─────────────────────┐
|
||||
JWT / API-key ──► auth ──► │ tenant_members │
|
||||
│ lookup → role │
|
||||
└─────────┬───────────┘
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ EnableRBAC? │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────────────────────┴────────────────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────────────┐ ┌──────────────────────┐
|
||||
│ false (default) │ │ true │
|
||||
│ role logged but │ │ role enforced; │
|
||||
│ not enforced; │ │ denials emit a 403 │
|
||||
│ ownership lookups │ │ AND a durable row │
|
||||
│ skipped entirely │ │ in audit_logs │
|
||||
└──────────────────────┘ └──────────────────────┘
|
||||
```
|
||||
|
||||
When `tenant.enable_rbac=false` (the shipped default):
|
||||
|
||||
- `RequireRole` middleware logs the would-be reject and lets the
|
||||
request through (`[rbac] role insufficient (logged but not
|
||||
enforced) ...`). Use these logs to audit your role assignments
|
||||
*before* flipping the flag.
|
||||
- `RequireOwnershipOrRole` short-circuits before even running its
|
||||
creator-lookup closure, so the dormant rollout window incurs zero
|
||||
extra DB roundtrips on hot mutation paths.
|
||||
- `audit_logs` only records member-management events
|
||||
(`rbac.member_added` etc.). Access-denied rows start landing only
|
||||
when enforcement is on.
|
||||
|
||||
When `tenant.enable_rbac=true`:
|
||||
|
||||
- Insufficient role → HTTP 403 + a durable
|
||||
`rbac.access_denied` row in `audit_logs` (subject to a 1-minute
|
||||
sliding-window dedup so probing clients can't fill the table).
|
||||
- Ownership lookup runs and decides whether the caller is the
|
||||
resource creator. Genuine "row missing" (404) is surfaced as 404,
|
||||
not 403, so client diagnostics still work.
|
||||
|
||||
## Configuration
|
||||
|
||||
YAML (`config/config.yaml`):
|
||||
|
||||
```yaml
|
||||
tenant:
|
||||
# Default false. Flip to true once role assignments have been audited.
|
||||
enable_rbac: false
|
||||
# Optional: leaves the existing cross-tenant superuser flag in place.
|
||||
enable_cross_tenant_access: false
|
||||
|
||||
auth:
|
||||
# self_serve (default) — anyone may register; new tenant + Owner
|
||||
# membership auto-created.
|
||||
# invite_only — public registration is rejected; new users
|
||||
# enter only via /tenants/:id/members invitations.
|
||||
registration_mode: self_serve
|
||||
```
|
||||
|
||||
Environment overrides (always win over YAML):
|
||||
|
||||
| Env var | YAML key | Values |
|
||||
|--------------------------------------|--------------------------------|------------------------------|
|
||||
| `WEKNORA_TENANT_ENABLE_RBAC` | `tenant.enable_rbac` | `true` / `false` |
|
||||
| `WEKNORA_AUTH_REGISTRATION_MODE` | `auth.registration_mode` | `self_serve` / `invite_only` |
|
||||
|
||||
The startup logger emits one line summarising both effective values
|
||||
plus their override sources, so you can confirm at boot which mode
|
||||
the deployment is in.
|
||||
|
||||
## Schema reference
|
||||
|
||||
### `tenant_members`
|
||||
|
||||
```sql
|
||||
CREATE TABLE tenant_members (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
user_id VARCHAR(36) NOT NULL,
|
||||
tenant_id BIGINT NOT NULL,
|
||||
role VARCHAR(32) NOT NULL, -- owner | admin | contributor | viewer
|
||||
status VARCHAR(32) NOT NULL DEFAULT 'active',
|
||||
joined_at TIMESTAMP WITH TIME ZONE,
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
|
||||
);
|
||||
CREATE UNIQUE INDEX idx_tenant_members_user_tenant_unique
|
||||
ON tenant_members(user_id, tenant_id) WHERE status = 'active';
|
||||
```
|
||||
|
||||
A user belongs to a tenant by having an `active` row in this table.
|
||||
The `(user_id, tenant_id)` uniqueness is conditional on `status =
|
||||
'active'` so historical revoked rows do not block a re-invite.
|
||||
|
||||
### Per-resource ownership
|
||||
|
||||
Migration 000043 added two columns the role check leans on:
|
||||
|
||||
- `knowledge_bases.creator_id VARCHAR(36)` — backfilled to the tenant
|
||||
Owner for legacy rows. Empty string / NULL means "tenant-owned, no
|
||||
human creator" and only role ≥ min may mutate.
|
||||
- `custom_agents.runnable_by_viewer BOOLEAN` — when true (default),
|
||||
Viewers can run the agent in chat without a role bump.
|
||||
|
||||
Sub-resources resolve up the ownership chain:
|
||||
|
||||
```
|
||||
chunk_id ─► knowledge_id ─► kb_id ─► knowledge_bases.creator_id
|
||||
```
|
||||
|
||||
Same for FAQ entries, generated questions, tags, and wiki pages.
|
||||
|
||||
### `audit_logs`
|
||||
|
||||
```sql
|
||||
CREATE TABLE audit_logs (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
tenant_id BIGINT NOT NULL,
|
||||
actor_user_id VARCHAR(36) NOT NULL DEFAULT '',
|
||||
actor_role VARCHAR(32) NOT NULL DEFAULT '',
|
||||
action VARCHAR(64) NOT NULL,
|
||||
target_type VARCHAR(32) NOT NULL DEFAULT '',
|
||||
target_id VARCHAR(64) NOT NULL DEFAULT '',
|
||||
target_user_id VARCHAR(36) NOT NULL DEFAULT '',
|
||||
request_path VARCHAR(512) NOT NULL DEFAULT '',
|
||||
request_method VARCHAR(16) NOT NULL DEFAULT '',
|
||||
outcome VARCHAR(16) NOT NULL DEFAULT 'success',
|
||||
details JSONB NOT NULL DEFAULT '{}'::JSONB,
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
Built-in actions today:
|
||||
|
||||
| Action | Outcome | When |
|
||||
|------------------------------|----------------------|------|
|
||||
| `rbac.member_added` | success | `POST /tenants/:id/members` succeeds |
|
||||
| `rbac.member_removed` | success | `DELETE /tenants/:id/members/:user_id` succeeds |
|
||||
| `rbac.member_role_changed` | success | `PUT /tenants/:id/members/:user_id` succeeds |
|
||||
| `rbac.member_left` | success | `POST /tenants/:id/members/leave` succeeds |
|
||||
| `rbac.access_denied` | denied | `RequireRole` / `RequireOwnershipOrRole` rejects (only when enforcement is on) |
|
||||
|
||||
The schema is intentionally generic so future PRs can add KB / agent /
|
||||
chunk action constants without another migration.
|
||||
|
||||
## Route guards
|
||||
|
||||
Centralised in `internal/router/rbac.go` as `rbacGuards`:
|
||||
|
||||
| Guard | What it requires |
|
||||
|------------------------------------------|------------------|
|
||||
| `g.Viewer()` | Tenant member, any role |
|
||||
| `g.Contributor()` | role ≥ Contributor |
|
||||
| `g.Admin()` | role ≥ Admin |
|
||||
| `g.Owner()` | role = Owner |
|
||||
| `g.OwnedKBOrAdmin()` | KB.creator_id == caller, OR Admin+ |
|
||||
| `g.OwnedKBOrAdminFromKbIDParam()` | Same, but reads `:kb_id` from a non-`:id` param |
|
||||
| `g.OwnedAgentOrAdmin()` | CustomAgent.creator_id == caller, OR Admin+ |
|
||||
| `g.OwnedKnowledgeKBOrAdmin()` | Resolves `:knowledge_id` → KB.creator_id |
|
||||
| `g.OwnedChunkKBOrAdmin()` | Resolves `:chunk_id` → knowledge → KB.creator_id |
|
||||
| `g.OwnedChunkKBOrAdminFromChunkID()` | Same chain, but starts from a different param name |
|
||||
| `g.OwnedWikiKBOrAdmin()` | Resolves wiki page → KB.creator_id |
|
||||
| `g.PathTenantMatch()` | URL `:tenant_id` matches the auth context |
|
||||
| `g.CrossTenant()` | Caller has cross-tenant access |
|
||||
|
||||
Read-only endpoints stay on `g.Viewer()`. Anything that mutates a
|
||||
shared infrastructure resource (Ollama install, parser/storage check,
|
||||
WeKnora Cloud credentials, web-search providers, vector stores,
|
||||
chat-history config) goes on `g.Admin()`. Anything per-resource picks
|
||||
the matching `Owned*OrAdmin` guard.
|
||||
|
||||
## Rollout playbook
|
||||
|
||||
The same playbook a self-host operator (or the Tencent/WeKnora repo
|
||||
itself) should follow when promoting a deployment from "logged" to
|
||||
"enforced":
|
||||
|
||||
1. **Upgrade.** `tenant.enable_rbac=false` (default) → schema lands,
|
||||
`tenant_members` is backfilled (one Owner per tenant, the rest
|
||||
Contributor), `creator_id` populated on every KB. No behaviour
|
||||
change yet.
|
||||
2. **Audit the membership.** Call
|
||||
`GET /api/v1/tenants/:id/members` (Admin+) and confirm:
|
||||
- Exactly one Owner per tenant.
|
||||
- The right humans are Contributors, Viewers, etc. (matters most
|
||||
in tenants where many users share an API key today and got
|
||||
auto-promoted to Contributor by the backfill).
|
||||
- Adjust with `PUT /api/v1/tenants/:id/members/:user_id` /
|
||||
`DELETE` as needed. Every change writes an `audit_logs` row.
|
||||
3. **Watch the dormant logs.** Tail the API logs for `[rbac] role
|
||||
insufficient (logged but not enforced)` lines. These tell you
|
||||
exactly which production calls *would* 403 if you flipped the
|
||||
flag now. Fix any user role that produces unexpected denials.
|
||||
4. **Flip the flag.** Set `tenant.enable_rbac=true` (or
|
||||
`WEKNORA_TENANT_ENABLE_RBAC=true`). Restart the app. From this
|
||||
point on:
|
||||
- Insufficient role → 403.
|
||||
- `audit_logs` records every reject (subject to dedup).
|
||||
5. **Optional — enable invite-only.** If you've moved off self-serve
|
||||
registration, set `auth.registration_mode=invite_only`. The
|
||||
Register tab disappears from `/login` and the server rejects
|
||||
`POST /auth/register` with 403.
|
||||
|
||||
### Rollback
|
||||
|
||||
If enforcement causes unexpected breakage:
|
||||
|
||||
```bash
|
||||
# Flip the flag back via env (no restart-with-rebuild needed):
|
||||
export WEKNORA_TENANT_ENABLE_RBAC=false
|
||||
# Restart the app.
|
||||
```
|
||||
|
||||
Membership rows and `creator_id` columns stay populated so re-enabling
|
||||
later doesn't require another backfill. Migration 000043 / 000044
|
||||
both ship `down.sql`s, but rolling those back drops `tenant_members`
|
||||
and `audit_logs` entirely — only do that if you intend to remove the
|
||||
feature for good.
|
||||
|
||||
## Frontend behaviour
|
||||
|
||||
The Pinia auth store exposes:
|
||||
|
||||
- `authStore.currentTenantRole` — `''` until membership resolves,
|
||||
then one of the four roles. Use the empty string as a "loading"
|
||||
signal; flashing a privileged button before the role is known is
|
||||
worse UX than waiting.
|
||||
- `authStore.hasRole('admin')` etc. — convenience helpers that walk
|
||||
the hierarchy.
|
||||
|
||||
Every mutation surface in the UI is gated either by a role check or
|
||||
by a per-resource ownership predicate (`isOwner` computed off
|
||||
`kb.creator_id === authStore.user?.id`). This is the matching pair
|
||||
to the backend guard — when a button would 403 on click, we hide the
|
||||
button instead of letting the user discover it through a failed
|
||||
request.
|
||||
|
||||
## Common questions
|
||||
|
||||
### "I upgraded and now everyone is a Contributor instead of an Admin."
|
||||
|
||||
The backfill picks **the earliest active user in each tenant** as
|
||||
that tenant's Owner; everyone else becomes Contributor. If a single
|
||||
human-shared account or API key created the tenant, you may need to
|
||||
demote bots and re-promote your real Admin via
|
||||
`PUT /api/v1/tenants/:id/members/:user_id`.
|
||||
|
||||
### "I flipped the flag and a script started getting 403."
|
||||
|
||||
Likely the script authenticates as a Viewer / Contributor instead of
|
||||
the Admin you assumed. Check the JWT user, look up the matching
|
||||
`tenant_members.role`, promote if appropriate. Or — if the script
|
||||
should be tenant-wide — switch it to authenticate via `X-API-Key`,
|
||||
which is pinned to Admin.
|
||||
|
||||
### "Why is the audit log not catching some 403s?"
|
||||
|
||||
Two reasons:
|
||||
|
||||
- Sliding-window dedup. The same `(actor, path, action)` tuple
|
||||
writes at most one durable row per minute. The full reject series
|
||||
is still in the perishable application log
|
||||
(`[rbac] role insufficient ...`).
|
||||
- Enforcement off. `rbac.access_denied` only writes when
|
||||
`tenant.enable_rbac=true`. The dormant mode just emits the warning
|
||||
log; member-management events do still write durably.
|
||||
|
||||
### "Can I have per-route ACL more granular than role + creator?"
|
||||
|
||||
Not in v1. The matrix is intentionally a small fixed lattice
|
||||
(Viewer < Contributor < Admin < Owner) with one ownership escape
|
||||
hatch per resource. Anything finer (e.g. "viewer can see audit log
|
||||
for their own actions") is a follow-up.
|
||||
|
||||
### "Where do I see the audit log in the UI?"
|
||||
|
||||
`Settings → Members → Audit Log` tab (Admin+ only). Cursor-paginated
|
||||
chronological feed with action / outcome chips. Filter UI is a v2.
|
||||
|
||||
## Testing & observability
|
||||
|
||||
- `make test` covers `internal/middleware/rbac_test.go`,
|
||||
`internal/handler/rbac_lookups_test.go`,
|
||||
`internal/application/service/audit_log_test.go` and
|
||||
`internal/middleware/rbac_audit_test.go` (~25 cases).
|
||||
- e2e smoke under both flag values is documented in #1303 PR
|
||||
series. The matrix that ships green: each role × each guarded
|
||||
route → expected status code.
|
||||
- Langfuse / OTel spans carry the resolved `TenantRole` and
|
||||
`TenantID`, so a denied request shows up as a single trace with
|
||||
the role on it — no need to correlate logs and traces by hand.
|
||||
Reference in New Issue
Block a user