randomparity / randomparity/kdive
Keycloak: emit kdive authorization claims (projects/roles/platform_roles/agent_session) via protocol mappers
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 1h 26m
- Merged PRs (30d)
- 311
Description
Now that Keycloak is reachable at `https://sso.drc.nz` (Cloudflare Tunnel), the remaining work to make it a real issuer for kdive is teaching it to emit kdive’s authorization claims.
## Background
`build_verifier` (`src/kdive/mcp/auth.py`) constructs a FastMCP `JWTVerifier` that enforces only the standard `iss`, `aud`, and JWKS signature. All authorization rides in custom claims parsed by `src/kdive/security/authz/context.py` and `src/kdive/security/authz/rbac.py`:
- `sub` — principal (required, non-empty)
- `aud` — must contain the configured audience (currently `kdive`)
- `projects` — JSON array of project names (`["proj-a","proj-b"]`)
- `roles` — JSON object mapping project to one role string, `viewer`<`operator`<`admin` (`{"proj-a":"admin"}`)
- `platform_roles` — JSON array of `platform_admin`/`platform_operator`/`platform_auditor` (optional)
- `agent_session` — string (optional)
- `azp`/`client_id` — used to resolve the actor map
Standard OIDC does not define `projects`/`roles`/`platform_roles`. Keycloak must be configured to emit them from its own user/group model.
## Scope
- Create a dedicated `kdive` realm.
- Decide the source of the claims (per the brainstorming notes: user/client attributes carrying JSON, vs Keycloak groups mapped via a script mapper). `roles` is a `{project: role}` object — a User-Attribute mapper with JSON claim type maps most directly to that shape.
- Add an Audience mapper so tokens carry `aud=kdive` (Keycloak does not add it by default).
- Add protocol mappers for `projects`, `roles`, `platform_roles`, and `agent_session`.
- Capture the realm as importable config (decided approach: importable realm JSON under `deploy/keycloak/`).
Needs a short design/spec first (claim source decision).
Contributor guide
Assessment
This issue has not been assessed yet.