Migrate cluster IdP from Authentik to Keycloak

Date: 2026-06-28 Status: Accepted Decision: hl-12i8 Deciders: Sean Brandt

Context

ADR hl-23m (2026-06) rejected migrating the cluster IdP to a DCR-native provider and chose an agentgateway mock-DCR short-circuit, on the premises that the short-circuit worked and that DCR was “too thin a reason” to migrate. Both premises collapsed: agentgateway’s McpIDP provider enum is Auth0 | Keycloak | Okta only (no Authentik adapter exists or is planned), so the clientId short-circuit is structurally unreachable against Authentik; and Keycloak GA plus agentgateway v1.3.1 GA ship real RFC 7591 DCR-proxy on the documented Keycloak adapter today. The cluster runs 18 Authentik applications across three provider types (13 OIDC, 4 forward-auth, 1 unused LDAP) that would require re-homing.

Decision

Migrate the cluster IdP from Authentik to Keycloak via a phased parallel run: stand Keycloak up as the MCP authorization server first (real DCR landed early, lowest blast radius), then migrate the 13 OIDC apps app-by-app, then replace the 4 forward-auth proxies with oauth2-proxy, then decommission Authentik last. This is option A (full migration) executed via a D-style transition that converges on a single-IdP end state.

Rationale

agentgateway’s McpIDP enum has no Authentik adapter; hl-23m’s core mechanism does not function, so the status quo cannot deliver real DCR.
Keycloak + agentgateway v1.3.1 deliver real DCR-proxy on shipped GA software — the primary criterion (time-to-real-DCR) is met with no unshipped-software bet.
Decisive criteria were time-to-real-DCR, minimal operational surface, and avoiding upstream-dependency risk; preserving the Authentik investment was explicitly NOT decisive.

Alternatives Considered

A — Full migration to Keycloak, phased parallel run (chosen): real DCR now on GA; single-IdP end state; cost is re-homing 18 apps and replacing the tf/authentik module.
B — Stay on Authentik, contribute an agentgateway Authentik adapter (rejected): requires two unshipped upstreams (Authentik DCR #8751 and an unwritten Rust adapter) — fails the upstream-dependency-risk criterion.
C — Status quo, static mcp-public client (rejected): structurally cannot deliver real RFC 7591 DCR — fails the time-to-real-DCR criterion.
D — Keycloak as a permanent MCP-only AS alongside Authentik (rejected as an end state): two IdPs forever — fails the minimal-operational-surface criterion; adopted only as the temporary transition shape.

Consequences

Positive: real RFC 7591 DCR on the MCP path lands in Phase 1 before any SSO app is touched; single-IdP end state removes dual-provider coordination overhead.
Negative: 18 apps must be re-homed; the tf/authentik Terraform module is replaced by tf/keycloak.
Neutral: Authentik stays live through Phases 0–4; each app cutover is independently reversible; supersedes ADR hl-23m.