randomparity / randomparity/kdive

Keycloak: emit kdive authorization claims (projects/roles/platform_roles/agent_session) via protocol mappers

Open
#349 0 comments 0 reactions 0 assignees View on GitHub
area:security effort:M priority:P1 risk:daytime-only status:ready type:feature
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.