Relationship-Based Access Control (ReBAC) | Kamiwaza Docs

Version: 1.0.1 (Latest)

Kamiwaza uses relationship-based access control (ReBAC) to enforce tenant-scoped and role-aware policies across the platform. This page summarizes the capabilities delivered with the current release, how to integrate an identity provider, and the operational practices required to keep the system healthy.

What ReBAC Delivers

Deny by default – every protected API checks for an explicit subject → relation → resource tuple before permitting access.
Context-aware policies – relations cover ownership, editor/viewer roles, clearance tiers, and nested group membership.
Runtime updates – policy manifests and tenant bootstrap files can be replayed without restarting services.
Auditable decisions – each authorization call records the decision, reason, backend, and correlation ID.
Shadow cutover – Postgres and SpiceDB can run in parallel to verify parity before promoting SpiceDB to the primary backend.
Automatic ownership tuples – when AUTH_REBAC_ENABLED=true, catalog/model uploads seed owner/editor/viewer tuples automatically so creators can immediately list and download their assets.

Architecture Snapshot

OIDC

Signed headers

Tuple checks

Read tuples

Allow / Deny response

User / Service

Auth Gateway

Model & Catalog APIs

Access Decision Engine

Relationship Store

SpiceDB (shadow/primary)

Component	Purpose	Notes
Auth Gateway	Terminates OIDC sessions, issues personal access tokens (PAT), forwards signed headers.	Keycloak is the reference IdP; OIDC, SAML, and CAC flows are supported when configured.
Access Decision Engine	Evaluates tuples stored in Postgres or SpiceDB and returns permit/deny with reasoning.	Targets <100 ms latency for typical requests.
Relationship Store	Persists tuple data and mirrors to SpiceDB when enabled.	Ships with default tuples for system tenants.
Service Guards	Wrap API endpoints with `enforce_*` helpers to require specific relations.	Catalog dataset deletes and model deletes ship protected in this release.
Policy Assets	`configs/rebac/policies/*.yaml` and tenant bootstraps under `configs/rebac/tenants/`.	Validate before applying changes.

Identity Provider Integration

Create a confidential client in your identity provider (Keycloak in the reference deployment).
- Client ID must match AUTH_GATEWAY_JWT_AUDIENCE (default kamiwaza-platform).
- Allowed redirect URI: the external URL of the Kamiwaza deployment (https://<gateway>/api/auth/callback).
Expose required claims in the ID token or user info endpoint.
- Include roles, tenant, and any clearance attributes referenced in policies.
- Ensure the token carries exp, iat, sub, and iss claims; Kamiwaza validates them on every request.
Configure the Auth Gateway through your deployment values, Kubernetes ConfigMaps, and Secrets.
- Set the issuer and JWKS URL to match your Keycloak realm (https://<keycloak>/realms/<realm> and /protocol/openid-connect/certs).
- Align AUTH_GATEWAY_JWT_AUDIENCE with the confidential client you created (kamiwaza-platform by default).
- Enable ReBAC (AUTH_REBAC_ENABLED=true) and choose your primary backend (postgres or spicedb).
- Point the session store at your Redis deployment (AUTH_REBAC_SESSION_REDIS_URL=rediss://<redis-host>:6380/0).
- Define the default tenant fallback (AUTH_REBAC_DEFAULT_TENANT_ID="__default__" for single-tenant labs) and enable PAT tagging (AUTH_PAT_TENANT_TAGGING_ENABLED=true) so newly issued tokens include tenant metadata.
- See the ReBAC Deployment Guide for the customer-facing rollout sequence and validation guidance.
Optional PAT workflow – use the Auth gateway PAT endpoint to issue automation tokens that embed tenant metadata.

Policy Management

Review your deployment's policy and tenant artifacts to understand the default relations for models, datasets, and administrative roles.
Validate changes before rollout using the supported administrative or deployment workflow for your environment.
Promote tenant and policy data through change management rather than editing live pods directly.
Capture evidence such as policy revisions, release records, and validation results for auditability.

Operations Checklist

Gateway policy – enable default_deny: true and explicitly list the /api/* paths users require.
Shadow validation – run with AUTH_REBAC_BACKEND=postgres and AUTH_REBAC_SHADOW_COMPARE=true until SpiceDB decisions match Postgres, then cut over.
Monitoring – tail structured rebac_decision logs today; metrics endpoints will be documented when generally available.
Session store – ensure Redis is served over TLS (rediss://), authentication is enabled, and session TTLs match your security policy (default 8 hours).
Audit artifacts – capture policy validation output, tuple plans, and decision logs for the release record.

Demonstrating ReBAC

For a walkthrough that exercises authentication, tuple enforcement, and observability expectations, follow the ReBAC Validation Checklist. It covers customer-facing sign-in, allow/deny checks, and log verification.

Limitations & Roadmap

ReBAC guards cover catalog, models, DDE connectors/documents, and retrieval job access. Additional services will continue to adopt guard coverage over time.
Some ingestion workflows are still admin-scoped; expand tuple policies if you need finer-grained controls for your administrators.

Need help integrating ReBAC or exporting evidence for accreditation? Reach out to your Kamiwaza support representative for the latest runbooks and automation scripts.

Next steps

Follow the ReBAC Deployment Guide to configure the deployment.
Run the ReBAC Validation Checklist to validate tuple enforcement and logging.