ReBAC Deployment Guide | Kamiwaza Docs

Documentation for Kamiwaza 0.11.0

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

Version: 0.11.0

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

Host meets the published system requirements. See System Requirements for the supported operating systems and hardware profiles.
Installation created the managed systemd units or Docker Compose stack for Auth, Keycloak, and Traefik.
You have shell access to restart those services and reach the Traefik gateway externally.

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. Leaving legacy lines overrides the helper output and will cause the Keycloak callback to fail.

Quick sanity check

Verify the new AUTH_GATEWAY_* block exists in env.sh by running grep AUTH_GATEWAY env.sh.

Generate a single ForwardAuth secret:

./scripts/rotate-auth-secrets.sh --secret AUTH_FORWARD_HEADER_SECRET --skip-compose

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


4. Confirm every staged env file reports the same secret:

```bash
grep AUTH_FORWARD_HEADER_SECRET env.sh runtime/oidc-uat.env \
       deployment/envs/${KAMIWAZA_ENV:-default}/kamiwaza-traefik/*/.env

If any of these values drift, Traefik forwards unsigned headers and the UI reports forward_auth_signature_invalid during model downloads.

Where to substitute values:

<keycloak-host> – the external hostname for the Keycloak realm.
<realm> – the Keycloak realm that contains the Kamiwaza client.
<gateway-host> – the public Traefik hostname for the Kamiwaza environment.
<client-secret> – only required if the kamiwaza-platform client is configured as confidential with client-secret authentication.
<redis-host> – the TLS endpoint of the Redis deployment used for ReBAC sessions.

After updating the file, reload it so the helper scripts and restart commands pick up the new values:

source env.sh

source runtime/oidc-uat.env   # generated by scripts/run_oidc_uat.sh

runtime/oidc-uat.env is the source of truth for the Keycloak client metadata.

Environment-specific Redis settings

Local labs usually run the bundled Redis instance without authentication:

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.

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:

export AUTH_REBAC_ALLOW_COMMUNITY_FALLBACK=true

export AUTH_REBAC_DEFAULT_TENANT_ID="__default__"

Only use these flags in local or UAT environments.

Logout redirect expectations

Set KAMIWAZA_UI_URL to the full UI base so logout returns users to the correct page.
The gateway only trusts forwarded hosts that match the allowed hosts.
Localhost fallback is used only when certain flags are set.

ReBAC manifest on RPM installs

The RPM does not include configs/rebac/tenants or a default manifest. ReBAC still runs, but no tuples are preseeded.

Seed ReBAC tuples

Before operators can download or deploy a model they must be granted the appropriate tuples:

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

Replace the manifest path with your tenant-specific file in production.

Optionally add ad-hoc tuples by editing the manifest and rerunning plan/bootstrap.

Apply the change:

python scripts/rebac_tenant.py plan configs/rebac/tenants/acme-labs.yaml

python scripts/rebac_tenant.py bootstrap configs/rebac/tenants/acme-labs.yaml

Production environments should rely on the automatic owner helper.

Quick smoke test

After the bootstrap, verify allow/deny flows:

Upload a dataset via the /api/catalog/datasets/ endpoint.

Confirm list calls work:

curl -H "Authorization: Bearer $TOKEN" https://<gateway>/api/catalog/datasets/

Expected: HTTP 200 with the uploaded dataset URN in the JSON payload.

Confirm direct lookups succeed:

curl -H "Authorization: Bearer $TOKEN" \
        "https://<gateway>/api/catalog/datasets/by-urn?urn=<dataset-urn>"

Expected: HTTP 200 with the dataset metadata.

If any of these values drift, re-run the bootstrap manifest.

Seed demo realm & client metadata

Run the helper to import the UAT realm, create the confidential client, and generate runtime/oidc-uat.env with matching values:

./scripts/run_oidc_uat.sh --no-smoke --skip-install --no-start-keycloak \
  --callback-url "https://<gateway-host>/api/auth/callback"

After generating the realm, reload your shell environment:

source env.sh

source runtime/oidc-uat.env

The helper writes runtime/oidc-uat.env with the gateway OIDC exports.

Restart core services

Bounce the authentication plane so the new settings apply:

If you installed via the developer bundle, use the deployment helpers:

export KAMIWAZA_SWARM_HEAD=true

sudo ./containers-down.sh keycloak

sudo ./containers-up.sh keycloak

sudo ./containers-down.sh traefik

sudo ./containers-up.sh traefik

./startup/kamiwazad.sh restart-core

If you made changes to the deployment assets, rerun ./copy-compose.sh before the restart.

Using an external identity provider

To exercise a managed provider, create an OIDC client there with the same redirect URI:

export AUTH_GATEWAY_KEYCLOAK_URL=https://accounts.google.com      # replace with provider base URL

export AUTH_GATEWAY_KEYCLOAK_REALM=<idp-tenant-or-realm>

export AUTH_GATEWAY_KEYCLOAK_CLIENT_ID=<issued-client-id>

export AUTH_GATEWAY_KEYCLOAK_CLIENT_SECRET=<issued-client-secret>

source env.sh

Skip run_oidc_uat.sh in that scenario.

Verify login & header passthrough

Visit https://<gateway-host>/api/auth/login and sign in with the credentials seeded by the helper.

Call the validation endpoint to ensure the session cookie works:

curl -ki https://<gateway-host>/api/auth/validate \
     -H "Cookie: access_token=<copied-session-cookie>"

Expect HTTP 200 with X-User-* headers.

If issues persist, resync the environment exports and restart the services:

source env.sh

source runtime/oidc-uat.env

./startup/kamiwazad.sh restart-core         # developer bundle

# or

sudo kamiwaza restart-core                  # RPM/DEB installs

Next steps

Walk through the ReBAC validation checklist to exercise tuple enforcement and decision logging.
Review the ReBAC overview for architecture context.