129 lines
2.7 KiB
Markdown
129 lines
2.7 KiB
Markdown
# 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.
|