Allow GitHub SSO to auto-create Keycloak accounts
Date: 2026-07-03 Status: Accepted Decision: hl-sqtn Deciders: Sean Brandt
Context
Section titled “Context”The fzymgc realm currently has registration_allowed = false — no direct
self-registration; accounts are operator/Terraform-provisioned. Adding GitHub
as a social identity provider (hl-d0md) raises a distinct question: should a
GitHub identity with no matching Keycloak account be allowed to auto-create
one on first login, or should GitHub login be restricted to linking
pre-existing accounts only.
Decision
Section titled “Decision”Configure keycloak_oidc_github_identity_provider with link_only = false,
so a GitHub identity with no matching Keycloak account auto-creates one via
Keycloak’s default first-broker-login flow.
Rationale
Section titled “Rationale”- Accepted as an explicit, confirmed decision despite materially widening the
account-creation surface beyond the realm’s
registration_allowed = falseposture. - No custom first-broker-login review/approval flow is added this phase; default Keycloak behavior is used as-is.
- Mitigation is deferred, not designed now: revisit with a custom approval flow or allow-list expression policy only if unwanted accounts appear.
Alternatives Considered
Section titled “Alternatives Considered”- link_only = false, auto-create on first GitHub login (chosen): zero-friction onboarding — any GitHub identity can self-provision via the default first-broker-login flow without operator involvement.
- link_only = true, GitHub requires a pre-existing linked account (rejected): keeps account creation exclusively operator/Terraform-provisioned, consistent with the realm’s closed registration posture, but removes the low-friction onboarding benefit that motivated adding GitHub login in the first place.
Consequences
Section titled “Consequences”- Positive: zero-friction GitHub sign-in and account onboarding without operator provisioning steps.
- Negative: any GitHub account holder can create a realm account — a bigger blast radius than the closed direct-registration form; no allow-list or approval gate constrains who can self-provision via GitHub yet.
- Neutral: existing users can still manually link GitHub via Account Console independent of the auto-create path for new identities.