pal-e-docs

Review: Keycloak service account for programmatic admin API access

review-785-2026-04-03 Doc

review block
Project

Verdict: BLOCK

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Standalone, discovered during email testing
  • [x] Repo — forgejo_admin/pal-e-services
  • [x] User Story — clear who/what/why
  • [x] Context — sufficient background
  • [x] File Targets — specific paths with modify/don't-touch guidance
  • [x] Acceptance Criteria — 7 testable conditions
  • [x] Test Expectations — curl commands and tofu plan
  • [x] Constraints — grant type, secret handling, pattern to follow
  • [x] Checklist — 4 discrete steps
  • [x] Related — project and blocking issues listed

Traceability

  • [ ] story:platform-S1 — DOES NOT EXIST in project-pal-e-platform user-stories. Valid keys: superuser-deploy, superuser-observe, superuser-recover, superuser-onboard-service. [LABEL] Change to story:superuser-deploy or story:superuser-onboard-service.
  • [ ] story note MISSING — [SCOPE] If a new story is intended, create user story entry on project-pal-e-platform user-stories section.
  • [x] arch:keycloak label — Keycloak component
  • [ ] arch note MISSING — No arch-keycloak note found in pal-e-docs. [SCOPE] Create architecture note arch-keycloak for the Keycloak component.
  • [x] Forgejo issue — #260, open

File Targets

  • [x] ~/pal-e-services/terraform/k3s.tfvars — verified exists, keycloak_clients map at line 40
  • [x] ~/pal-e-services/terraform/keycloak.tf — confirmed: service_accounts_enabled at line 114, service account role binding at line 168
  • [x] ~/pal-e-services/terraform/k3s.tfvars.example — confirmed: commented-out service account example at lines 41-49
File targets are accurate. The infrastructure code exists and supports the proposed change.

Repo Placement

MISMATCH. Issue is filed on forgejo_admin/pal-e-platform but issue body correctly states the work is in forgejo_admin/pal-e-services. The Forgejo issue should be on the pal-e-services repo. [BODY] Refile on forgejo_admin/pal-e-services.

Dependencies

  • [x] keycloak.tf resources — satisfied (service account support already exists)
  • [x] variables.tf schema — satisfied (service_accounts_enabled optional bool at line 124)
  • [ ] basketball-api #311, #312, #313 — listed as blocked by this ticket, but need re-evaluation given existing westside-ai-bot client

Acceptance Criteria

7 AC are individually testable and specific (tofu plan output, curl token acquisition, endpoint auth check, secret storage, SOP creation). However, the AC are moot — the existing westside-ai-bot client already satisfies the core need. AC should be re-evaluated after the scope question is resolved.

Blast Radius

CRITICAL: The ticket's core assumption is wrong. k3s.tfvars already contains a service account client at lines 102-112:
This is a confidential client with service_accounts_enabled = true and service_account_realm_roles = ["admin"] in the westside-basketball realm — exactly what the ticket proposes to create. The claim that "no programmatic auth path exists" is incorrect.
Before creating a new platform-service client, verify whether westside-ai-bot can already serve this purpose via client_credentials grant. If the secret is unknown, retrieve it from Keycloak admin console or tofu state show.

Decomposition Assessment

1 file target, 1 repo, ~8 lines of code. No decomposition needed IF the ticket survives scope validation. The change itself is well within the five-minute rule and three-thing limit. However, the ticket cannot proceed until the fundamental scope question is resolved: is this work even necessary given the existing westside-ai-bot client?

Recommendation

  • [SCOPE] Verify whether westside-ai-bot client already satisfies this need. Test: curl -X POST https://keycloak.tail5b443a.ts.net/realms/westside-basketball/protocol/openid-connect/token -d grant_type=client_credentials -d client_id=westside-ai-bot -d client_secret=.... If it works, close this issue as unnecessary.
  • [SCOPE] If a separate client IS justified (separation of concerns), update the Context section to explain why westside-ai-bot is insufficient.
  • [LABEL] Change story:platform-S1 to a valid story key (story:superuser-deploy or story:superuser-onboard-service).
  • [SCOPE] Create architecture note arch-keycloak for the Keycloak component in pal-e-docs.
  • [BODY] Refile issue on forgejo_admin/pal-e-services (not pal-e-platform).