# 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**](https://docs.kamiwaza.ai/).

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](https://docs.kamiwaza.ai/0.11.0/installation/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.

```bash
# 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

1. Verify the new `AUTH_GATEWAY_*` block exists in `env.sh` by running `grep AUTH_GATEWAY env.sh`.
2. Generate a single ForwardAuth secret:
   
   ```bash
   ./scripts/rotate-auth-secrets.sh --secret AUTH_FORWARD_HEADER_SECRET --skip-compose
   ```

3. Rerun `./copy-compose.sh`, then bounce Traefik and the core stack:
   
   ```bash
   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:

```bash
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:

```bash
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:

```bash
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:

1. **Bootstrap the tenant manifest (recommended).**

```bash
   python scripts/rebac_tenant.py bootstrap configs/rebac/tenants/__default__.yaml
   ```

Expected output:
   
   ```text
   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.

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

Apply the change:

```bash
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:
1. Upload a dataset via the `/api/catalog/datasets/` endpoint.
2. Confirm list calls work:
   
   ```bash
   curl -H "Authorization: Bearer $TOKEN" https://<gateway>/api/catalog/datasets/
   ```

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

3. Confirm direct lookups succeed:
   
   ```bash
   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:

```bash
./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:

```bash
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:

```bash
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:

```bash
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

1. Visit `https://<gateway-host>/api/auth/login` and sign in with the credentials seeded by the helper.
2. Call the validation endpoint to ensure the session cookie works:
   
   ```bash
   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:

```bash
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](https://docs.kamiwaza.ai/0.11.0/security/rebac-validation-checklist) to exercise tuple enforcement and decision logging.
- Review the [ReBAC overview](https://docs.kamiwaza.ai/0.11.0/security/rebac-overview) for architecture context.