Spike: Keycloak integration and role-based schema design

ldraney commented

2026-06-07 15:21:48 +00:00

Owner

Type

Spike

Lineage

Standalone — palinks is evolving from single-user to multi-user with role-based link visibility and feature flags. Need to design how Keycloak auth maps to the Rails data model and how it's provisioned across platform repos.

Repo

Multiple — palinks, pal-e-platform, pal-e-services, pal-e-deployments

Question

How should Keycloak roles integrate with the palinks Rails schema to support role-scoped links and feature flags?

Keycloak setup: Does a palinks realm already exist, or do we need a new one? Do we create a new client? How are roles (superadmin, member) defined — realm roles vs client roles?
Rails schema: Current schema has only a links table (no users, no clicks, no feature flags). What tables/columns are needed?
- Do we store a users table that mirrors Keycloak subjects, or rely entirely on token claims?
- How does links.visibility work — enum column with values public, member, superadmin? Hierarchy-based scope check?
- Where do feature flag toggles live — separate table, or user preferences JSONB?
Role model reconciliation: The canonical role model is two Keycloak roles (superadmin, member) plus anonymous (unauthenticated). Confirm this aligns with docs/visibility.md and docs/architecture.md. No other roles needed at this stage.
OIDC flow: Which Rails gem for OIDC? omniauth-keycloak? devise + OIDC? Bare openid_connect gem?
Platform provisioning:
- pal-e-platform: Is there existing Keycloak infra to reuse? Realm config?
- pal-e-services: Terraform changes needed — Keycloak client, secrets, OIDC config?
- pal-e-deployments: New secrets (client ID, client secret, realm URL) in SOPS overlay?

Deliverables

Required outputs:

docs/auth.md created — consolidates auth design from existing docs/architecture.md and docs/visibility.md into a single reference. Covers Keycloak integration, role mapping, schema plan, and OIDC gem decision.
Follow-up tickets created: Rails migration(s), Keycloak client provisioning, secrets wiring, OIDC gem integration

Time-box

3 hours

palinks — the service being integrated
pal-e-platform — Keycloak cluster lives here
pal-e-services — Terraform provisioning
pal-e-deployments — k8s secrets and overlay
ldraney/palinks #15 — custom domain (may affect OIDC redirect URIs)
ldraney/palinks #17 — visibility tier definitions (depends on this spike's role model)
ldraney/palinks #19 — seed data (consumes schema decisions from this spike)

### Type Spike ### Lineage Standalone — palinks is evolving from single-user to multi-user with role-based link visibility and feature flags. Need to design how Keycloak auth maps to the Rails data model and how it's provisioned across platform repos. ### Repo Multiple — `palinks`, `pal-e-platform`, `pal-e-services`, `pal-e-deployments` ### Question How should Keycloak roles integrate with the palinks Rails schema to support role-scoped links and feature flags? - **Keycloak setup**: Does a `palinks` realm already exist, or do we need a new one? Do we create a new client? How are roles (superadmin, member) defined — realm roles vs client roles? - **Rails schema**: Current schema has only a `links` table (no users, no clicks, no feature flags). What tables/columns are needed? - Do we store a `users` table that mirrors Keycloak subjects, or rely entirely on token claims? - How does `links.visibility` work — enum column with values `public`, `member`, `superadmin`? Hierarchy-based scope check? - Where do feature flag toggles live — separate table, or user preferences JSONB? - **Role model reconciliation**: The canonical role model is two Keycloak roles (superadmin, member) plus anonymous (unauthenticated). Confirm this aligns with `docs/visibility.md` and `docs/architecture.md`. No other roles needed at this stage. - **OIDC flow**: Which Rails gem for OIDC? `omniauth-keycloak`? `devise` + OIDC? Bare `openid_connect` gem? - **Platform provisioning**: - `pal-e-platform`: Is there existing Keycloak infra to reuse? Realm config? - `pal-e-services`: Terraform changes needed — Keycloak client, secrets, OIDC config? - `pal-e-deployments`: New secrets (client ID, client secret, realm URL) in SOPS overlay? ### Deliverables Required outputs: - [ ] `docs/auth.md` created — consolidates auth design from existing `docs/architecture.md` and `docs/visibility.md` into a single reference. Covers Keycloak integration, role mapping, schema plan, and OIDC gem decision. - [ ] Follow-up tickets created: Rails migration(s), Keycloak client provisioning, secrets wiring, OIDC gem integration ### Time-box 3 hours ### Related - `palinks` — the service being integrated - `pal-e-platform` — Keycloak cluster lives here - `pal-e-services` — Terraform provisioning - `pal-e-deployments` — k8s secrets and overlay - `ldraney/palinks #15` — custom domain (may affect OIDC redirect URIs) - `ldraney/palinks #17` — visibility tier definitions (depends on this spike's role model) - `ldraney/palinks #19` — seed data (consumes schema decisions from this spike)

ldraney referenced this issue

2026-06-07 15:31:53 +00:00

Update docs for multi-user portfolio vision #20

ldraney commented

2026-06-07 15:32:22 +00:00

Author

Owner

Scope Review: NEEDS_REFINEMENT

Review note: review-1378-2026-06-07

Spike template is complete and well-structured, but traceability backing notes are missing and existing docs reveal a role model inconsistency that this spike should reconcile.

Issues found:

[SCOPE] project-palinks note missing in pal-e-docs -- cannot verify story:auth-roles traceability
[SCOPE] arch-palinks note missing in pal-e-docs -- no architecture backing note (repo has docs/architecture.md but it's not mirrored)
[BODY] Role model inconsistency: issue says 2 roles (superadmin, member); docs/architecture.md defines 4 roles (admin, collaborator, lead, public); docs/visibility.md defines 3 tiers (superadmin, member, public). Spike should reconcile these.
[BODY] Deliverable overlap: docs/architecture.md and docs/visibility.md already contain substantial Keycloak design. Clarify whether docs/auth.md consolidates or supplements existing docs.
[BODY] Undocumented downstream dependencies: #17 (visibility tier assignment) and #19 (dev seed data) depend on this spike's schema decisions.

## Scope Review: NEEDS_REFINEMENT Review note: `review-1378-2026-06-07` Spike template is complete and well-structured, but traceability backing notes are missing and existing docs reveal a role model inconsistency that this spike should reconcile. **Issues found:** - **[SCOPE]** `project-palinks` note missing in pal-e-docs -- cannot verify story:auth-roles traceability - **[SCOPE]** `arch-palinks` note missing in pal-e-docs -- no architecture backing note (repo has `docs/architecture.md` but it's not mirrored) - **[BODY]** Role model inconsistency: issue says 2 roles (superadmin, member); `docs/architecture.md` defines 4 roles (admin, collaborator, lead, public); `docs/visibility.md` defines 3 tiers (superadmin, member, public). Spike should reconcile these. - **[BODY]** Deliverable overlap: `docs/architecture.md` and `docs/visibility.md` already contain substantial Keycloak design. Clarify whether `docs/auth.md` consolidates or supplements existing docs. - **[BODY]** Undocumented downstream dependencies: #17 (visibility tier assignment) and #19 (dev seed data) depend on this spike's schema decisions.

ldraney referenced this issue

2026-06-07 15:33:47 +00:00

Update docs for multi-user portfolio vision #20

ldraney referenced this issue

2026-06-07 15:35:31 +00:00

Spike: Define link visibility tiers and assign current links #17

ldraney referenced this issue

2026-06-07 15:46:29 +00:00

Update docs for multi-user portfolio vision #20

ldraney commented

2026-06-07 15:47:24 +00:00

Author

Owner

Scope Review: APPROVED

Review note: review-1378-2026-06-07-r2

Re-review of all 5 previous findings — all resolved:

project-palinks and arch-palinks notes created in pal-e-docs with proper traceability
Role model reconciliation question added to issue body; docs/architecture.md and docs/visibility.md aligned to superadmin/member/anonymous
Deliverable clarified as consolidation of existing docs into docs/auth.md
Dependencies on #17 and #19 documented in Related section

Ticket is ready for next_up.

## Scope Review: APPROVED Review note: `review-1378-2026-06-07-r2` Re-review of all 5 previous findings — all resolved: - `project-palinks` and `arch-palinks` notes created in pal-e-docs with proper traceability - Role model reconciliation question added to issue body; `docs/architecture.md` and `docs/visibility.md` aligned to superadmin/member/anonymous - Deliverable clarified as consolidation of existing docs into `docs/auth.md` - Dependencies on #17 and #19 documented in Related section Ticket is ready for next_up.

ldraney referenced this issue from a pull request that will close it,

2026-06-07 16:33:05 +00:00

Spike: Keycloak auth integration design #23

ldraney referenced this issue

2026-06-07 16:33:22 +00:00

Spike: Visibility tier definitions and link audit #24

ldraney referenced this issue

2026-06-07 16:33:55 +00:00

Spike: Custom domain routing for palinks.app #25

ldraney referenced this issue

2026-06-07 16:34:48 +00:00

Spike: Custom domain routing for palinks.app #25