Use k8s structured auth config for dual-issuer OIDC transition
Date: 2026-06-28 Status: Superseded by hl-idws Decision: hl-9rhj Deciders: Sean Brandt
Context
Section titled “Context”k3s exposes OIDC trust via a single --oidc-issuer-url flag; an atomic switch from Authentik to Keycloak would invalidate all existing kubectl OIDC sessions simultaneously. Kubernetes AuthenticationConfiguration (v1beta1, default-on since 1.30) supports a slice of JWT authenticators and is applied on k3s via the --authentication-config server flag.
Decision
Section titled “Decision”Apply an AuthenticationConfiguration (v1beta1) on k3s via --authentication-config that trusts both the Authentik and Keycloak JWT authenticators concurrently during migration, then remove the Authentik authenticator at Phase 5.
Rationale
Section titled “Rationale”- Structured auth config enables incremental per-user migration without invalidating existing sessions.
- An atomic
--oidc-issuer-urlswitch has no rollback path once sessions are invalidated. - v1beta1
AuthenticationConfigurationis default-on since k8s 1.30 — no feature gate required.
Alternatives Considered
Section titled “Alternatives Considered”- Structured auth config with dual JWT authenticators (chosen): both issuers trusted concurrently; each user migrates independently; reversible by removing an entry; cost is a k3s config-file edit and server restart.
- Atomic
--oidc-issuer-urlflag switch (rejected): simpler single flag, but invalidates all Authentik-issued sessions at once with no safe parallel run.
Consequences
Section titled “Consequences”- Positive: the k8s OIDC migration is independently reversible with no session disruption; establishes a reusable mechanism for adding future OIDC providers without a session-breaking change.
- Negative: a k3s server restart is required to apply config-file changes.
- Neutral: the dual-authenticator config collapses to a single Keycloak entry at Phase 5.
References
Section titled “References”- Superseded by: hl-idws