Use groups-claim model for Phase 2 OIDC authz; defer roles to Phase 4
Use groups-claim model for Phase 2 OIDC authz; defer roles to Phase 4
Section titled “Use groups-claim model for Phase 2 OIDC authz; defer roles to Phase 4”Date: 2026-06-30 Status: Accepted Decision: hl-tir8 Deciders: Sean Brandt
Context
Section titled “Context”Keycloak Phase 2 must carry per-app authorization from Authentik into the fzymgc realm. Keycloak offers two token-based models: a groups claim (shared client scope + group-membership protocol mapper) or realm/client roles. A repo-wide survey found all five authorizing apps (Vault, ArgoCD, Mealie, clickstack, karakeep) consume a groups claim that mirrors the Authentik group names 1:1; zero read a roles claim. The parent migration (ADR hl-12i8) sequenced a groups→roles overlay into Phase 4.
Decision
Section titled “Decision”Emit a groups claim via a single shared keycloak_openid_client_scope carrying a keycloak_openid_group_membership_protocol_mapper (claim_name=groups, full_path=false), attached as a default scope only to clients that gate on groups. Keycloak realm/client roles are deferred to Phase 4, where the Phase-2 groups become the role-assignment containers.
Rationale
Section titled “Rationale”- All five authorizing apps read a
groupsclaim and none read roles — a roles overlay in Phase 2 forces app-side changes for zero functional gain. - 1:1 mirroring of Authentik group names keeps the authorization chain (user→group→claim→app policy) structurally unchanged at cutover, minimizing blast radius.
- A single shared scope is the idiomatic Keycloak pattern (context7-confirmed) and avoids per-client mapper duplication.
- Phase-2 groups are explicitly designed as the role-assignment containers for the Phase-4 roles overlay — the work is additive, not throwaway.
- Keycloak nested groups (vault, mealie) propagate correctly, retiring the Authentik #15159 double-bind workaround.
Alternatives Considered
Section titled “Alternatives Considered”- Groups-claim via shared client scope (chosen): zero app-side change; mirrors Authentik 1:1; lowest cutover risk; forward-compatible with Phase-4 roles. Downsides: groups are not Keycloak’s native authz primitive; authorization services unavailable until roles arrive.
- Keycloak realm/client roles (rejected for Phase 2): native authz primitive, aligns with Keycloak idiom — but requires changing every authorizing app’s claim path (none read roles today), needs a parallel groups+roles claim during transition, and duplicates the Phase-4 overlay prematurely.
Consequences
Section titled “Consequences”- Positive: zero app-side authorization change for Phase 2; group gating is opt-in per client; Phase-4 roles overlay inherits a ready group taxonomy.
- Negative: Keycloak authorization services (per-client group-access gating) are unavailable until Phase 4;
groupsclaim grows with realm size. - Neutral: nested-group propagation eliminates the Authentik double-bind workaround for vault/mealie.