Accept open-realm client access; defer per-client group gating to Keycloak authz services

Date: 2026-06-30 Status: Accepted Decision: hl-6bib Deciders: Sean Brandt

Context

Authentik gates “who can log in at all” via policy_engine_mode=any + group policy bindings on each provider — a user not in the bound group cannot complete the auth flow. Keycloak does not enforce this by default: any realm user can authenticate to any enabled client. Two Phase 2 apps — clickstack/HyperDX (hyperdx-user) and karakeep (karakeep-users) — relied solely on the Authentik access policy for gating and do not read the groups claim to self-authorize. The cluster runs ~3 users, all trusted (operator-class).

Decision

Accept that clickstack and karakeep (and any future login-only client) are reachable by any realm user under Keycloak. Still emit the groups claim on those clients so a future gating pass retains the data. Per-client group gating via Keycloak authorization services is deferred (not scheduled to a specific phase).

Rationale

The homelab runs ~3 all-trusted users — the access-policy gap is accepted risk, not an oversight.
Keycloak authorization services add a resource-server + policy + permission per client (significant Terraform surface) for zero marginal security benefit in this trust model.
Emitting the groups claim on login-only clients preserves optionality: if an app starts reading it, or authz services are added later, the data is already present.
Documenting the decision (plan “Access-gating semantics” section) ensures future contributors read this as intentional, not a missed Authentik feature.

Alternatives Considered

Accept open-realm semantics for the 3-user homelab (chosen): no authz-services complexity; groups claim still emitted for forward-compat; consistent with the trust model. Downside: any realm user can log into clickstack/karakeep — a regression vs Authentik policy-binding behavior.
Keycloak authorization-services per-client group gating (deferred): replicates Authentik’s policy-binding semantics with explicit IdP-level access control — but requires a resource server + policy + permission per client, a non-trivial Terraform addition unjustified by the current threat model.

Consequences

Positive: Phase 2 Terraform surface stays minimal (no authorization-services resources); groups claim on login-only clients is forward-compatible data.
Negative: clickstack and karakeep are reachable by any realm user, a regression vs Authentik; restoring per-client gating later requires adding Keycloak authorization-services resources.
Neutral: the change is scoped to login-only apps; group-gated apps (Vault, ArgoCD, Mealie) retain app-side authorization via the groups claim.