ldraney/pal-e-platform

Fork 0

Create westside-admin Keycloak client + document SOP (admin-console procedure) #301

New issue

Open

opened 2026-04-25 22:02:56 +00:00 by forgejo_admin · 3 comments

forgejo_admin commented

2026-04-25 22:02:56 +00:00

Contributor

Type

Task

Lineage

Companion to westside-admin scaffolding. Independent of app code; blocks forgejo_admin/westside-admin#2 (auth implementation needs the client to exist) and forgejo_admin/pal-e-deployments#133 (overlay's KEYCLOAK_CLIENT_SECRET secret depends on this).

Scope-revision lineage: Original ticket assumed terraform-managed Keycloak clients. Scope review (review-1096-2026-04-25) discovered:

~/pal-e-platform/keycloak.tf does not exist
Keycloak terraform at terraform/modules/keycloak/main.tf only deploys the SERVER (namespace, secret, PVC, deployment, service, theme configmap) — zero keycloak_openid_client resources
terraform/providers.tf does not declare the keycloak provider
Existing westside-basketball realm + westside-app client are admin-console-managed, not IaC
Outage risk if a dev agent declares a fresh keycloak_realm resource without tofu import — would collide with live realm and could overwrite theme/policies/users, breaking westside-app SSO

Decision (path A — admin-console + SOP): match the existing pattern (manual creation), document the procedure as a queryable SOP in pal-e-docs. Defer IaC migration to a separate epic if/when desired.

Repo

forgejo_admin/pal-e-platform (the SOP file lives in pal-e-docs as a note, but the procedure itself is platform-team responsibility, hence this ticket here for tracking)

User Story

story-westside-admin-admin-row-crud (project: westside-admin). Implements the Keycloak side of the admin gate safety constraint.

Scope

Two deliverables, both must complete:

1. Create the OIDC client manually via Keycloak admin console at https://keycloak.tail5b443a.ts.net/admin (admin user). Realm: westside-basketball. New client config:

Client ID: westside-admin
Client type: OpenID Connect
Access type: public (PKCE-only) — no client secret simplifies the SvelteKit cookie SSR flow. Confidential is also fine if the existing westside-app client is confidential — match the pattern.
PKCE Code Challenge Method: S256 (enforce in advanced settings)
Standard Flow Enabled: ON
Implicit Flow Enabled: OFF
Direct Access Grants Enabled: OFF
Service Accounts Enabled: OFF
Valid Redirect URIs: https://westside-admin.tail5b443a.ts.net/auth/callback
Web Origins: https://westside-admin.tail5b443a.ts.net
Front-channel Logout Enabled: ON (recommended for SLO)

If confidential client chosen: copy the generated client secret into the westside-admin-secrets Kubernetes Secret in pal-e-deployments/overlays/westside-admin/prod/westside-admin-secrets.enc.yaml (SOPS-encrypted). Coordinate with forgejo_admin/pal-e-deployments#133.

2. Create a queryable SOP in pal-e-docs documenting this procedure. Note slug: sop-keycloak-client-creation. Tag: sop,active. The note should:

Describe the manual admin-console procedure step-by-step (with screenshots if practical)
Document the admin URL, realm conventions, required client config fields
Document how to capture and store client secrets (if confidential)
Note that this is the current convention (admin-console-managed, NOT IaC) and link to the discovered-scope investigation in review-1096-2026-04-25
Cross-reference the existing westside-app client as the pattern reference

After both steps complete: verify https://keycloak.tail5b443a.ts.net/realms/westside-basketball/.well-known/openid-configuration is reachable; verify the new client appears in the Keycloak admin console.

Acceptance Criteria

New westside-admin client visible in Keycloak admin console under realm westside-basketball
Client config matches all bullets in Scope step 1
If confidential: client secret stored in pal-e-deployments overlay's SOPS-encrypted Secret
SOP note sop-keycloak-client-creation created in pal-e-docs with tag sop,active
SOP describes the manual procedure end-to-end such that a future agent or human can follow it without prior Keycloak knowledge
SOP references existing westside-app client as the pattern source
No terraform changes are made in this ticket (defer IaC migration to a separate epic)
https://keycloak.tail5b443a.ts.net/realms/westside-basketball/.well-known/openid-configuration returns realm config (sanity check Keycloak is reachable)

Test Expectations

Manual: open Keycloak admin console, verify client config matches ACs
Manual: from a debug pod or workstation, hit the .well-known endpoint and verify it lists the new client (or at least the realm — clients aren't always public)
Future verification: after forgejo_admin/westside-admin#2 lands, the auth flow against this client succeeds end-to-end

Constraints

DO NOT add the mrparkers/keycloak terraform provider in this ticket (out of scope; deferred to a separate IaC epic)
DO NOT declare any keycloak_realm resource — would collide with live realm and could break westside-app SSO
DO NOT modify the existing westside-app client
DO NOT change realm-level settings
Match the public-vs-confidential choice of the existing westside-app client (inspect its config first)

Checklist

Client created in admin console
Client secret (if confidential) propagated to pal-e-deployments overlay Secret
SOP note sop-keycloak-client-creation created in pal-e-docs
No terraform changes made
PR description (in pal-e-deployments if secret was added there, or N/A if no PR needed) documents that this ticket is admin-console + SOP, with rationale linking to review-1096-2026-04-25

project-westside-admin
arch-deployment-westside-admin
review-1096-2026-04-25 (scope investigation that drove path A)
feedback_funnel_requires_auth
BLOCKS: forgejo_admin/westside-admin#2 (auth code), forgejo_admin/pal-e-deployments#133 (overlay secrets)

### Type Task ### Lineage Companion to westside-admin scaffolding. Independent of app code; blocks `forgejo_admin/westside-admin#2` (auth implementation needs the client to exist) and `forgejo_admin/pal-e-deployments#133` (overlay's KEYCLOAK_CLIENT_SECRET secret depends on this). **Scope-revision lineage:** Original ticket assumed terraform-managed Keycloak clients. Scope review (`review-1096-2026-04-25`) discovered: - `~/pal-e-platform/keycloak.tf` does not exist - Keycloak terraform at `terraform/modules/keycloak/main.tf` only deploys the SERVER (namespace, secret, PVC, deployment, service, theme configmap) — zero `keycloak_openid_client` resources - `terraform/providers.tf` does not declare the `keycloak` provider - Existing `westside-basketball` realm + `westside-app` client are admin-console-managed, not IaC - **Outage risk** if a dev agent declares a fresh `keycloak_realm` resource without `tofu import` — would collide with live realm and could overwrite theme/policies/users, breaking westside-app SSO Decision (path A — admin-console + SOP): match the existing pattern (manual creation), document the procedure as a queryable SOP in pal-e-docs. Defer IaC migration to a separate epic if/when desired. ### Repo `forgejo_admin/pal-e-platform` (the SOP file lives in pal-e-docs as a note, but the procedure itself is platform-team responsibility, hence this ticket here for tracking) ### User Story `story-westside-admin-admin-row-crud` (project: westside-admin). Implements the Keycloak side of the admin gate safety constraint. ### Scope Two deliverables, both must complete: **1. Create the OIDC client manually via Keycloak admin console** at https://keycloak.tail5b443a.ts.net/admin (admin user). Realm: `westside-basketball`. New client config: - Client ID: `westside-admin` - Client type: OpenID Connect - Access type: **public** (PKCE-only) — no client secret simplifies the SvelteKit cookie SSR flow. Confidential is also fine if the existing westside-app client is confidential — match the pattern. - PKCE Code Challenge Method: `S256` (enforce in advanced settings) - Standard Flow Enabled: ON - Implicit Flow Enabled: OFF - Direct Access Grants Enabled: OFF - Service Accounts Enabled: OFF - Valid Redirect URIs: `https://westside-admin.tail5b443a.ts.net/auth/callback` - Web Origins: `https://westside-admin.tail5b443a.ts.net` - Front-channel Logout Enabled: ON (recommended for SLO) If confidential client chosen: copy the generated client secret into the `westside-admin-secrets` Kubernetes Secret in `pal-e-deployments/overlays/westside-admin/prod/westside-admin-secrets.enc.yaml` (SOPS-encrypted). Coordinate with `forgejo_admin/pal-e-deployments#133`. **2. Create a queryable SOP in pal-e-docs** documenting this procedure. Note slug: `sop-keycloak-client-creation`. Tag: `sop,active`. The note should: - Describe the manual admin-console procedure step-by-step (with screenshots if practical) - Document the admin URL, realm conventions, required client config fields - Document how to capture and store client secrets (if confidential) - Note that this is the current convention (admin-console-managed, NOT IaC) and link to the discovered-scope investigation in `review-1096-2026-04-25` - Cross-reference the existing westside-app client as the pattern reference After both steps complete: verify `https://keycloak.tail5b443a.ts.net/realms/westside-basketball/.well-known/openid-configuration` is reachable; verify the new client appears in the Keycloak admin console. ### Acceptance Criteria - [ ] New `westside-admin` client visible in Keycloak admin console under realm `westside-basketball` - [ ] Client config matches all bullets in Scope step 1 - [ ] If confidential: client secret stored in pal-e-deployments overlay's SOPS-encrypted Secret - [ ] SOP note `sop-keycloak-client-creation` created in pal-e-docs with tag `sop,active` - [ ] SOP describes the manual procedure end-to-end such that a future agent or human can follow it without prior Keycloak knowledge - [ ] SOP references existing westside-app client as the pattern source - [ ] No terraform changes are made in this ticket (defer IaC migration to a separate epic) - [ ] `https://keycloak.tail5b443a.ts.net/realms/westside-basketball/.well-known/openid-configuration` returns realm config (sanity check Keycloak is reachable) ### Test Expectations - Manual: open Keycloak admin console, verify client config matches ACs - Manual: from a debug pod or workstation, hit the .well-known endpoint and verify it lists the new client (or at least the realm — clients aren't always public) - Future verification: after `forgejo_admin/westside-admin#2` lands, the auth flow against this client succeeds end-to-end ### Constraints - DO NOT add the `mrparkers/keycloak` terraform provider in this ticket (out of scope; deferred to a separate IaC epic) - DO NOT declare any `keycloak_realm` resource — would collide with live realm and could break westside-app SSO - DO NOT modify the existing westside-app client - DO NOT change realm-level settings - Match the public-vs-confidential choice of the existing westside-app client (inspect its config first) ### Checklist - [ ] Client created in admin console - [ ] Client secret (if confidential) propagated to pal-e-deployments overlay Secret - [ ] SOP note `sop-keycloak-client-creation` created in pal-e-docs - [ ] No terraform changes made - [ ] PR description (in pal-e-deployments if secret was added there, or N/A if no PR needed) documents that this ticket is admin-console + SOP, with rationale linking to `review-1096-2026-04-25` ### Related - `project-westside-admin` - `arch-deployment-westside-admin` - `review-1096-2026-04-25` (scope investigation that drove path A) - `feedback_funnel_requires_auth` - BLOCKS: `forgejo_admin/westside-admin#2` (auth code), `forgejo_admin/pal-e-deployments#133` (overlay secrets)

forgejo_admin commented

2026-04-25 22:08:19 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-1096-2026-04-25

Ticket premise is incorrect: there is no terraform-managed Keycloak client to "clone." The keycloak terraform provider is not configured in terraform/providers.tf, no keycloak_realm resource exists, and no keycloak_openid_client resources exist anywhere in terraform/. The westside-basketball realm and existing westside-app client are managed via the Keycloak admin console, not IaC.

Issues:

~/pal-e-platform/keycloak.tf does not exist. Keycloak terraform lives at terraform/modules/keycloak/main.tf and only manages the server (deployment/svc/PVC/theme).
[SCOPE] Decide bootstrap strategy: configure keycloak provider + import realm in this ticket, or land a separate "adopt Keycloak under IaC" ticket first.
[SCOPE] Decide public+PKCE vs confidential client.
[SCOPE] Create architecture note arch-keycloak (label has no backing note).
[BODY] Fix file path reference and replace "clone the westside-app client" guidance.
[BODY] Add explicit AC for realm management (data lookup vs import) with zero realm-level drift.
Outage risk: declaring keycloak_realm for westside-basketball without import would 409 or overwrite realm settings (theme, users), breaking westside-app SSO for Lucas and Marcus.
[DECOMPOSE] After SCOPE answered: split into provider+realm-adoption / client-resource / (optional) secret-export. Route to skill-decompose-ticket.

Full findings in the review note.

## Scope Review: NEEDS_REFINEMENT Review note: `review-1096-2026-04-25` Ticket premise is incorrect: there is no terraform-managed Keycloak client to "clone." The `keycloak` terraform provider is not configured in `terraform/providers.tf`, no `keycloak_realm` resource exists, and no `keycloak_openid_client` resources exist anywhere in `terraform/`. The `westside-basketball` realm and existing `westside-app` client are managed via the Keycloak admin console, not IaC. Issues: - `~/pal-e-platform/keycloak.tf` does not exist. Keycloak terraform lives at `terraform/modules/keycloak/main.tf` and only manages the server (deployment/svc/PVC/theme). - `[SCOPE]` Decide bootstrap strategy: configure keycloak provider + import realm in this ticket, or land a separate "adopt Keycloak under IaC" ticket first. - `[SCOPE]` Decide public+PKCE vs confidential client. - `[SCOPE]` Create architecture note `arch-keycloak` (label has no backing note). - `[BODY]` Fix file path reference and replace "clone the westside-app client" guidance. - `[BODY]` Add explicit AC for realm management (data lookup vs import) with zero realm-level drift. - Outage risk: declaring `keycloak_realm` for `westside-basketball` without import would 409 or overwrite realm settings (theme, users), breaking westside-app SSO for Lucas and Marcus. - `[DECOMPOSE]` After SCOPE answered: split into provider+realm-adoption / client-resource / (optional) secret-export. Route to `skill-decompose-ticket`. Full findings in the review note.

forgejo_admin changed title from ~~Terraform: Keycloak OIDC client westside-admin in westside-basketball realm~~ to Create westside-admin Keycloak client + document SOP (admin-console procedure)

2026-04-25 22:34:41 +00:00

forgejo_admin commented

2026-04-25 23:42:23 +00:00

Author

Contributor

Scope Review: APPROVED

Review note: review-1096-2026-04-25-v2

Path A rewrite resolves all v1 findings. False premise removed, outage risk avoided via explicit Constraints, two deliverables (admin-console client + sop-keycloak-client-creation SOP) are tightly coupled and fit a single agent pass. ACs testable, dependencies cleanly documented.

Non-blocking carryover:

[SCOPE] arch-keycloak architecture note still missing — track as a separate backlog item; SOP partially compensates. Do not block #1096.

Ready to advance backlog → todo.

## Scope Review: APPROVED Review note: `review-1096-2026-04-25-v2` Path A rewrite resolves all v1 findings. False premise removed, outage risk avoided via explicit Constraints, two deliverables (admin-console client + `sop-keycloak-client-creation` SOP) are tightly coupled and fit a single agent pass. ACs testable, dependencies cleanly documented. Non-blocking carryover: - `[SCOPE]` `arch-keycloak` architecture note still missing — track as a separate backlog item; SOP partially compensates. Do not block #1096. Ready to advance backlog → todo.

forgejo_admin commented

2026-04-25 23:57:57 +00:00

Author

Contributor

SOP authored as sop-keycloak-client-creation in pal-e-docs (project: pal-e-platform, tags: sop, active, keycloak).

Scope of this PR-less delivery: ticket explicitly forbids terraform changes (Constraints) and the realm/clients are admin-console-managed per review-1096-2026-04-25. There is no repo file target — the SOP note IS the deliverable.

Coverage of ACs:

AC: SOP sop-keycloak-client-creation created with tag sop,active
AC: SOP describes the manual procedure end-to-end (11 numbered steps covering admin URL, realm selection, General Settings, Capability config, Login settings, Logout settings, Advanced/PKCE, Credentials retrieval, SOPS overlay propagation, .well-known verification, end-to-end verification)
AC: References existing westside-app client as the public+PKCE pattern reference; westside-admin as the cookie-SSR/confidential pattern
AC: No terraform changes
AC (manual, requires admin console action by Lucas/admin): client westside-admin created in westside-basketball realm with config matching the SOP's "OIDC Client Config Summary" table
AC (conditional, blocked by client creation): if confidential client chosen, client_secret stored in pal-e-deployments/overlays/westside-admin/prod/westside-admin-secrets.enc.yaml per ticket #133
AC (sanity): https://keycloak.tail5b443a.ts.net/realms/westside-basketball/.well-known/openid-configuration reachable — this is verifiable now from any tailnet device

Additions beyond ticket scope (intentional, captured by review feedback):

Dedicated State Parameter / CSRF Requirement section spelling out that consuming apps MUST implement OIDC state validation on /auth/callback (Keycloak does not enforce this; review feedback flagged this as a gap in the original Track A design).
Dedicated Secret Handling section with rotation procedure.
Standardized as a generalized SOP (not westside-admin-specific) so it applies to all future client creations against the realm.

Discovered scope (not filed as a separate ticket — flagging for Ava):

arch-keycloak architecture note is referenced by review-1096-2026-04-25 as missing. The SOP cross-references arch-deployment-westside-admin as a substitute, but the dedicated arch-keycloak note documenting the IaC vs admin-console-managed boundary is still absent. Worth a separate ticket if Ava agrees.

Handoff: this ticket is doc-complete on the SOP side. Closing it requires the manual admin-console action (which I cannot perform — live realm). Recommend Ava decides whether to (a) keep this open until Lucas runs the SOP and creates the client, or (b) split into two issues (SOP done now, client creation tracked separately as a manual ops task). Per dispatch instructions I will NOT close the ticket myself.

SOP authored as `sop-keycloak-client-creation` in pal-e-docs (project: `pal-e-platform`, tags: `sop, active, keycloak`). **Scope of this PR-less delivery:** ticket explicitly forbids terraform changes (Constraints) and the realm/clients are admin-console-managed per `review-1096-2026-04-25`. There is no repo file target — the SOP note IS the deliverable. **Coverage of ACs:** - [x] AC: SOP `sop-keycloak-client-creation` created with tag `sop,active` - [x] AC: SOP describes the manual procedure end-to-end (11 numbered steps covering admin URL, realm selection, General Settings, Capability config, Login settings, Logout settings, Advanced/PKCE, Credentials retrieval, SOPS overlay propagation, .well-known verification, end-to-end verification) - [x] AC: References existing `westside-app` client as the public+PKCE pattern reference; `westside-admin` as the cookie-SSR/confidential pattern - [x] AC: No terraform changes - [ ] AC (manual, requires admin console action by Lucas/admin): client `westside-admin` created in `westside-basketball` realm with config matching the SOP's "OIDC Client Config Summary" table - [ ] AC (conditional, blocked by client creation): if confidential client chosen, client_secret stored in `pal-e-deployments/overlays/westside-admin/prod/westside-admin-secrets.enc.yaml` per ticket #133 - [ ] AC (sanity): `https://keycloak.tail5b443a.ts.net/realms/westside-basketball/.well-known/openid-configuration` reachable — this is verifiable now from any tailnet device **Additions beyond ticket scope (intentional, captured by review feedback):** - Dedicated **State Parameter / CSRF Requirement** section spelling out that consuming apps MUST implement OIDC `state` validation on `/auth/callback` (Keycloak does not enforce this; review feedback flagged this as a gap in the original Track A design). - Dedicated **Secret Handling** section with rotation procedure. - Standardized as a generalized SOP (not westside-admin-specific) so it applies to all future client creations against the realm. **Discovered scope (not filed as a separate ticket — flagging for Ava):** - `arch-keycloak` architecture note is referenced by `review-1096-2026-04-25` as missing. The SOP cross-references `arch-deployment-westside-admin` as a substitute, but the dedicated `arch-keycloak` note documenting the IaC vs admin-console-managed boundary is still absent. Worth a separate ticket if Ava agrees. Handoff: this ticket is doc-complete on the SOP side. Closing it requires the manual admin-console action (which I cannot perform — live realm). Recommend Ava decides whether to (a) keep this open until Lucas runs the SOP and creates the client, or (b) split into two issues (SOP done now, client creation tracked separately as a manual ops task). Per dispatch instructions I will NOT close the ticket myself.

forgejo_admin referenced this issue

2026-04-26 00:00:35 +00:00

feat(database): provision admin_app Postgres role on basketball-api (#302) #304

forgejo_admin referenced this issue from a commit

2026-05-03 14:37:43 +00:00

secrets(westside-admin): land real KEYCLOAK_CLIENT_SECRET from Keycloak