Skip to content

Identity: External Keycloak

Date: 2026-03-23 Status: In progress Context: Adding authentication and authorization to platform tools (ArgoCD, Harbor, Grafana) to enable multi-user access for coaches and advanced students

Decision

Use Keycloak as the identity provider for platform tools, hosted outside the Kubernetes cluster rather than running it as a workload inside the platform.

Rationale

Why Keycloak?

  • Open-source and flexible — supports OIDC, SAML, and a wide range of identity federation options. No vendor lock-in.
  • Well-supported integrations — ArgoCD, Harbor, and Grafana all have native OIDC/Keycloak support.
  • Self-hosted — user identity data stays under our control.

Why external, not inside the cluster?

  • The cluster is disposable — we don't have a long-term contract on the EduCloud infrastructure, and we lack a clear backup strategy (see ADR-PLATFORM-005: Storage). Running an identity provider on infrastructure that may disappear is a liability.
  • User data doesn't belong in the cluster — Keycloak stores user accounts, credentials, and group memberships. Keeping this data outside the cluster avoids mixing user identity with ephemeral student workloads.
  • Independent lifecycle — Keycloak can survive cluster rebuilds, upgrades, or migrations. If the cluster is reprovisioned, authentication continues to work.

Alternatives Considered

Keycloak inside the cluster

  • ✅ Single infrastructure to manage
  • ❌ User data at risk if cluster is lost (no reliable backup with local-path-provisioner)
  • ❌ Ties identity provider lifecycle to cluster lifecycle
  • Rejected: Too risky given our infrastructure constraints

Authelia / Authentik

  • ✅ Lightweight alternatives
  • ❌ Less mature, smaller ecosystems
  • ❌ Fewer built-in integrations with our tool stack
  • Rejected: Keycloak's flexibility and ecosystem support are worth the slightly heavier footprint

Per-tool local accounts

  • ✅ No additional infrastructure
  • ❌ Doesn't scale — separate credentials for each tool
  • ❌ No single sign-on, no central user management
  • Current state for some tools (Grafana anonymous, Harbor/ArgoCD with admin accounts) — being migrated away from

Consequences

Positive

  • Single sign-on across ArgoCD, Harbor, and Grafana
  • Coaches can access platform tools with their own accounts
  • User identity is decoupled from cluster lifecycle
  • Enables scoped access for Tier 2 self-service (students managing their own deployments)

Negative

  • Additional infrastructure to host and maintain outside the cluster
  • Network dependency between cluster and external Keycloak instance
  • Adds OIDC configuration complexity to each integrated tool