ADR-0002: Keycloak as the identity provider for the MVP
Synced read-only from
/home/synnet/synvirt-platform/docs-internal/adr/0002-identity-provider-keycloak.md. Edit at the source, not here.
ADR-0002: Keycloak as the identity provider for the MVP
Section titled “ADR-0002: Keycloak as the identity provider for the MVP”- Status: Accepted
- Date: 2026-06-28
Context
Section titled “Context”The platform needs central SSO across web, portal, API and community (Discourse), with MFA, passkeys/WebAuthn and social login (Google, Microsoft). Candidates: Keycloak (mature, JVM) and Kanidm (Rust-native, aligned with our stack).
Decision
Section titled “Decision”Use Keycloak for the MVP. It has proven OIDC/SSO, DiscourseConnect support, passkeys, and ready-made Google/Microsoft logins. Keycloak runs isolated — never part of the product core. Kanidm is a post-MVP candidate to re-evaluate.
Realm synvirt is exported to infra/keycloak/realm-synvirt.json and imported
on startup. Clients: synvirt-web (OIDC), synvirt-portal-api (bearer-only),
synvirt-discourse (SSO). The portal API validates JWTs via the realm’s JWKS.
Consequences
Section titled “Consequences”- Fast path to MFA/passkeys/social login and Discourse SSO.
- A JVM service to operate and harden; kept on the internal network behind Caddy.
- Migrating to Kanidm later means re-issuing clients and re-pointing OIDC config; app code only depends on standard OIDC, easing the swap.
Migratability
Section titled “Migratability”Keycloak owns the keycloak logical database and connects via its own URL, so it
can move to a dedicated identity host (Host C) without touching other services.