# Runbook - Keycloak OIDC (Wave 2 Track 1)

## Scope

This runbook covers the enterprise identity baseline introduced in Wave 2 Track 1:

- Keycloak-backed OIDC login
- signed application bearer tokens
- controlled fallback to local login

It is for QA and enterprise-like environments, not the default demo flow.

## Modes

### Local / demo

- `OIDC_ENABLED=0`
- `ALLOW_LEGACY_HEADER_AUTH=1`

Use this when:

- running local demos
- using seeded local users
- preserving existing Stage 1-4 scripts

### QA transition

- `OIDC_ENABLED=1`
- `ALLOW_LEGACY_HEADER_AUTH=1`

Use this when:

- validating OIDC without breaking old header-based scripts
- checking dual-mode compatibility before cutover

### Enterprise pilot

- `OIDC_ENABLED=1`
- `ALLOW_LEGACY_HEADER_AUTH=0`

Use this when:

- OIDC is the primary login path
- bearer-token validation is enforced end-to-end

## Required configuration

- `APP_TOKEN_SECRET`
- `APP_TOKEN_TTL_SECONDS` (default `3600`)
- `OIDC_ENABLED`
- `OIDC_PROVIDER=keycloak`
- `OIDC_ISSUER_URL`
- `OIDC_CLIENT_ID`
- `OIDC_CLIENT_SECRET`
- `OIDC_REDIRECT_URI`
- `OIDC_SCOPES` (default `openid profile email`)
- `OIDC_ROLE_CLAIM` (default `groups`)
- `OIDC_ROLE_MAP_JSON`
- `ALLOW_LEGACY_HEADER_AUTH`

Default role map:

```json
{
  "kc_admin": "admin",
  "kc_supervisor": "supervisor",
  "kc_operator": "operator",
  "kc_analyst": "analyst"
}
```

## Keycloak client settings

Recommended client type:

- confidential client
- standard authorization code flow enabled
- PKCE enabled

Redirect URI:

- `https://<gateway-host>/proxy/auth/auth/oidc/callback`

Web origins:

- `https://<gateway-host>`

## Validation flow

1. Apply migrations:
   - `python scripts/migrate_core_db.py`
2. Start the stack with Track 1 env vars.
3. Check OIDC endpoints:
   - `python scripts/oidc_smoke.py --base-url http://<gateway-host> --require-enabled`
4. Open:
   - `http://<gateway-host>/operator`
5. Click `Корпоративный вход`.
6. Complete Keycloak login.
7. Confirm the operator UI receives a session and continues using bearer auth.

## Failure handling

### OIDC health fails

- verify `OIDC_ISSUER_URL`
- verify Keycloak realm is reachable from the auth-service
- verify TLS and reverse proxy settings

### Login returns `403`

- verify user groups in Keycloak
- verify `OIDC_ROLE_MAP_JSON`
- verify `OIDC_ROLE_CLAIM` matches the actual claim in the ID token

### Existing scripts stop working

- in QA only, temporarily set `ALLOW_LEGACY_HEADER_AUTH=1`
- in enterprise pilot, do not revert silently; update the script/client to bearer auth or use documented break-glass local login only

## Break-glass local access

Local `/auth/login` remains available in Track 1 for:

- local development
- demo mode
- break-glass admin access

It is not the primary path in enterprise mode.