call-center/docs/runbooks/keycloak-oidc.md

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:

{
  "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.