ReBAC Deployment Guide | Kamiwaza Docs

This is documentation for Kamiwaza 0.9.3, which is no longer actively maintained. For the current GA release, see 1.0.1.

Version: 0.9.3

Use this guide to bring the Kamiwaza authentication and relationship-based access control (ReBAC) stack online for lab, pilot, or production deployments. It assumes you have installed the current Kamiwaza platform bundle (RPM or container images) and can restart services via the provided scripts.

Platform assumptions

Prerequisites

Item Notes
Keycloak 22.x+ Administrative access to create a realm and confidential client.
Kamiwaza platform install Current RPM build (or the equivalent compose stack).
Shell access Ability to edit env.sh, run helper scripts, and restart Auth/Keycloak/Traefik.
TLS assets Certificates for the public gateway hostname (self-signed is fine for labs).

Before starting, stop the Auth, Keycloak, and Traefik services (docker compose or systemd) so configuration changes and realm imports apply cleanly. You will restart them later in this guide.

Configure environment

Update env.sh (or export the variables directly) with the ReBAC settings below. Replace the placeholders with values that match your environment.

# Auth gateway ↔ Keycloak

export AUTH_GATEWAY_OIDC_ENABLED=true

export AUTH_GATEWAY_KEYCLOAK_URL=https://<keycloak-host>

export AUTH_GATEWAY_KEYCLOAK_REALM=<realm>

export AUTH_GATEWAY_KEYCLOAK_CLIENT_ID=kamiwaza-platform

export AUTH_CALLBACK_URL=https://<gateway-host>/api/auth/callback

# Optional: only set if the Keycloak client enforces confidential secret auth

# export AUTH_GATEWAY_KEYCLOAK_CLIENT_SECRET=<client-secret>

export AUTH_GATEWAY_PUBLIC_URL=https://<gateway-host>

export AUTH_GATEWAY_COOKIE_DOMAIN=<gateway-host>

# ForwardAuth secret shared with Traefik

export AUTH_FORWARD_AUTH_STRICT=true

export AUTH_FORWARD_HEADER_SECRET=<64-hex-secret>

# ReBAC session store

export AUTH_REBAC_ENABLED=true

export AUTH_REBAC_BACKEND=postgres

export AUTH_REBAC_SESSION_ENABLED=true

export AUTH_REBAC_SESSION_REDIS_URL=rediss://<redis-host>:6380/0

export AUTH_REBAC_SESSION_ALLOW_INSECURE=false  # set true only for localhost labs

# Tenant defaults & PAT tagging

export AUTH_REBAC_DEFAULT_TENANT_ID="__default__"  # single-tenant labs; omit for multi-tenant installs

export AUTH_PAT_TENANT_TAGGING_ENABLED=true        # ensures new PATs include tenant_id

# Optional: override only if you must disable automatic tuple writes (defaults to true when ReBAC is enabled)

# export AUTH_DATASET_OWNER_TUPLES_ENABLED=true

# ForwardAuth policy file (stateless requirement)

export AUTH_GATEWAY_POLICY_FILE=$KAMIWAZA_ROOT/config/auth_gateway_policy.yaml

Avoid stale overrides

If env.sh already contains older AUTH_GATEWAY_* exports, remove or comment them before adding the block above.

Quick sanity check

  1. Verify only the new AUTH_GATEWAY_* block exists in env.sh by running grep AUTH_GATEWAY env.sh. The helper-generated runtime/oidc-uat.env should report the same values.
  2. Generate a single ForwardAuth secret and let the rotation helper copy it everywhere:
./scripts/rotate-auth-secrets.sh --secret AUTH_FORWARD_HEADER_SECRET --skip-compose
  1. Rerun ./copy-compose.sh, then bounce Traefik and the core stack:
sudo ./containers-down.sh traefik && sudo ./containers-up.sh traefik

./startup/kamiwazad.sh restart-core
  1. Confirm every staged env file reports the same secret:
grep AUTH_FORWARD_HEADER_SECRET env.sh runtime/oidc-uat.env \

deployment/envs/${KAMIWAZA_ENV:-default}/kamiwaza-traefik/*/.env

Environment-specific Redis settings

Local labs usually run the bundled Redis instance without authentication. In that case, export:

export AUTH_REBAC_SESSION_ALLOW_INSECURE=true

export AUTH_REBAC_SESSION_REDIS_URL=redis://localhost:6379/0

As soon as you point the gateway at a secured or shared Redis deployment, switch to a credentialed URL—e.g. rediss://user:pass@redis.example.com:6380/0—and omit AUTH_REBAC_SESSION_ALLOW_INSECURE.

Tenant fallback for labs

Stage‑1 bundles do not yet stamp tenant_id into the access token. Until the Keycloak protocol mapper is in place, allow the gateway to fall back to the __default__ tenant by exporting:

export AUTH_REBAC_ALLOW_COMMUNITY_FALLBACK=true

export AUTH_REBAC_DEFAULT_TENANT_ID="__default__"

Only use these flags in local or UAT environments. As soon as tokens carry real tenant metadata, remove both exports so ReBAC enforces per-tenant policy.

Seed ReBAC tuples

Before operators can download or deploy a model they must be granted the appropriate tuples in the target tenant.

  1. Bootstrap the tenant manifest (recommended).
python scripts/rebac_tenant.py bootstrap configs/rebac/tenants/__default__.yaml

Expected output:

INFO:kamiwaza.services.auth.bootstrap:Applied tenant bootstrap

INFO:rebac_tenant:Tenant bootstrap applied successfully
  1. Optionally add ad-hoc tuples by editing the manifest and rerunning plan/bootstrap. Example entry:
relationships:

- subject: user:analyst@example.com

relation: viewer

object: dataset:govdocs-ingest

Next steps

Troubleshooting