[Spike] Keycloak-gated public forms — identity via auth, not self-ID #59

New issue

Open

opened 2026-04-10 21:46:50 +00:00 by forgejo_admin · 0 comments

forgejo_admin commented

2026-04-10 21:46:50 +00:00

Contributor

Type

Spike

Lineage

Standalone — emerged 2026-04-10 while scoping jersey-public.html (issue #57). Interim fix: Email field added to the public form as a reconciliation key. This spike evaluates whether the next generation of outreach forms (tryout interest, waiver, fundraising opt-in, tournament RSVP, etc.) should instead require Keycloak login so identity is never self-declared.

Repo

multiple — forgejo_admin/westside-landing (frontend auth), forgejo_admin/basketball-api (backend user mapping), forgejo_admin/pal-e-platform (Keycloak realm config)

Question

Should we require Keycloak login before any public outreach form can be submitted, and if yes, what's the lightest-weight auth flow (magic link? password? first-time self-registration?) that Westside families will actually complete?

What to Explore

Keycloak Admin Console (keycloak.tail5b443a.ts.net, realm pal-e): check existing user base, see if parents / players already have Keycloak accounts, verify whether the realm has passwordless/magic-link flow enabled
basketball-api code: read routes/checkout.py and any existing keycloak_user dependency to see how JWT claims are consumed today. Check for a keycloak_sub column on parents / players tables (if absent, plan the backfill)
westside-landing code: check current /login / /account routes and how the SvelteKit app handles redirect-to-keycloak. Determine whether we can reuse an existing pattern or have to build one
Migration path: quantify how many existing parents / players rows would need to be mapped to Keycloak users (and whether email is reliably populated on both sides for matching)
UX experiment: walk through the proposed flow as a non-technical parent would — phone browser, first time, no password saved. Count taps. If it's > 6 taps from "click link in text" to "form shown," it's probably too much friction and we stick with email-based intake
Consult: feedback_keycloak_first.md (prior guidance to prefer Keycloak built-ins). No human consultation needed beyond Lucas for the go/no-go decision

Success Criteria

Question is answered with evidence — actual Keycloak realm inspection + actual code reads, not speculation
Recommended auth flow named (magic link / password / hybrid) with rationale
Tap-count walkthrough recorded (concrete UX friction measurement)
keycloak_sub schema gap documented (exists? needs adding? backfill plan?)
Follow-up ticket created — either "implement Keycloak gate on next outreach form" or a closing comment documenting "stick with email-based intake, here's why"
Spike doc in pal-e-docs: slug spike-keycloak-gated-forms, tagged spike,active, tied to project westside-basketball

Time-box

Maximum: 1 session, 2–4 hours. If the Keycloak realm inspection alone blows the budget, stop and escalate — that itself is a finding (it means the auth surface is under-documented and the spike has to become a doc-then-reassess ticket).

westside-basketball — project this affects
story:WS-S31 — the user story that prompted this spike (public jersey intake)
forgejo_admin/westside-playground#57 — interim email-based solution
feedback_keycloak_first.md — prior guidance: check Keycloak built-ins before building custom auth
arch-generic-checkout — existing parent-token flow (System C) for reference on how identity currently attaches to orders

### Type Spike ### Lineage Standalone — emerged 2026-04-10 while scoping `jersey-public.html` (issue #57). Interim fix: Email field added to the public form as a reconciliation key. This spike evaluates whether the *next* generation of outreach forms (tryout interest, waiver, fundraising opt-in, tournament RSVP, etc.) should instead require Keycloak login so identity is never self-declared. ### Repo multiple — `forgejo_admin/westside-landing` (frontend auth), `forgejo_admin/basketball-api` (backend user mapping), `forgejo_admin/pal-e-platform` (Keycloak realm config) ### Question Should we require Keycloak login before any public outreach form can be submitted, and if yes, what's the lightest-weight auth flow (magic link? password? first-time self-registration?) that Westside families will actually complete? ### What to Explore - **Keycloak Admin Console** (`keycloak.tail5b443a.ts.net`, realm `pal-e`): check existing user base, see if `parents` / `players` already have Keycloak accounts, verify whether the realm has passwordless/magic-link flow enabled - **basketball-api code:** read `routes/checkout.py` and any existing `keycloak_user` dependency to see how JWT claims are consumed today. Check for a `keycloak_sub` column on `parents` / `players` tables (if absent, plan the backfill) - **westside-landing code:** check current `/login` / `/account` routes and how the SvelteKit app handles redirect-to-keycloak. Determine whether we can reuse an existing pattern or have to build one - **Migration path:** quantify how many existing `parents` / `players` rows would need to be mapped to Keycloak users (and whether email is reliably populated on both sides for matching) - **UX experiment:** walk through the proposed flow as a non-technical parent would — phone browser, first time, no password saved. Count taps. If it's > 6 taps from "click link in text" to "form shown," it's probably too much friction and we stick with email-based intake - **Consult:** `feedback_keycloak_first.md` (prior guidance to prefer Keycloak built-ins). No human consultation needed beyond Lucas for the go/no-go decision ### Success Criteria - [ ] Question is answered with evidence — actual Keycloak realm inspection + actual code reads, not speculation - [ ] Recommended auth flow named (magic link / password / hybrid) with rationale - [ ] Tap-count walkthrough recorded (concrete UX friction measurement) - [ ] `keycloak_sub` schema gap documented (exists? needs adding? backfill plan?) - [ ] Follow-up ticket created — either "implement Keycloak gate on next outreach form" or a closing comment documenting "stick with email-based intake, here's why" - [ ] Spike doc in pal-e-docs: slug `spike-keycloak-gated-forms`, tagged `spike,active`, tied to project `westside-basketball` ### Time-box Maximum: **1 session, 2–4 hours**. If the Keycloak realm inspection alone blows the budget, stop and escalate — that itself is a finding (it means the auth surface is under-documented and the spike has to become a doc-then-reassess ticket). ### Related - `westside-basketball` — project this affects - `story:WS-S31` — the user story that prompted this spike (public jersey intake) - `forgejo_admin/westside-playground#57` — interim email-based solution - `feedback_keycloak_first.md` — prior guidance: check Keycloak built-ins before building custom auth - `arch-generic-checkout` — existing parent-token flow (System C) for reference on how identity currently attaches to orders

Commenting is not possible because the repository is archived.

No labels

No milestone

No project

No assignees

1 participant

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

ldraney/westside-playground#59

No description provided.

Rows
Columns