Skip to content

feat(sandbox): add keycloak to the sandbox stack with an imported demo realm - #316

Merged
tiana-code merged 1 commit into
mainfrom
feat/E-06-keycloak-sandbox
Jun 19, 2026
Merged

feat(sandbox): add keycloak to the sandbox stack with an imported demo realm#316
tiana-code merged 1 commit into
mainfrom
feat/E-06-keycloak-sandbox

Conversation

@tiana-code

Copy link
Copy Markdown
Owner

F-06.8 (#315) - Keycloak in the sandbox compose stack. Prerequisite for #236 (owner delegated the auth decision; chose Option 1: a real IdP, not an auth-bypass).

What

  • A keycloak service (quay.io/keycloak/keycloak:26.6.1, start-dev --import-realm) with deploy/keycloak/fincore-realm.json: a fincore-demo client-credentials client whose 8 dedicated default client scopes (ledger/payments/decision/compliance read+write) land in the token scope claim, mapping to the services' SCOPE_ authorities.
  • Issuer pinned via KC_HOSTNAME so every token carries iss=http://keycloak:8080/realms/fincore; ledger + payments validate against that in-network issuer (JWKS discovered by service name). Keycloak is published on host port 8085 so the demo can fetch a token; the host-fetched token still validates because iss is not origin-bound.
  • Healthcheck via the documented Keycloak bash /dev/tcp probe of :9000/health/ready (the image ships no curl/wget); depends_on keycloak service_started (the lazy decoder means services need the IdP only at first token validation).
  • compose-smoke: --wait-timeout 90->180; a new auth-chain-proof step fetches a client_credentials token and calls a protected ledger AND payments endpoint expecting 200 - proving realm import, scope claim, issuer match, JWKS discovery and Spring scope mapping in this slice.
  • A path-scoped gitleaks allowlist for the documented sandbox demo secret.

Security

This STRENGTHENS security: it replaces an unused issuer placeholder with a real validating issuer. No SecurityConfig changes, no auth-bypass; the services still require valid JWTs. The demo secret is sandbox-only (start-dev, never in Helm/prod).

Gate chain

  • architect (opus): designed the issuer scheme + realm + CI (plan.md).
  • critic (opus): GO-WITH-CHANGES; must-fixes applied (whitespace-agnostic HTTP/1.1 200 health probe; KC tag aligned to the in-repo 26.6.1).
  • security-auditor (opus): PASS, no must-fix (security-strengthening; client_credentials only; no backdoor; allowlist minimal).
  • code-reviewer: 2 must-fixes adjudicated and DECLINED with evidence - the Keycloak image has no curl so /dev/tcp is the correct (and officially documented) healthcheck, and docker compose up --wait already waits on keycloak's healthcheck so service_started is correct; its 2 recommendations were APPLIED (payments-scope assertion; gitleaks anchored + script path).
  • evaluator: PASS (0.84).
    Cannot run compose locally; the compose-smoke CI job is the integration gate.

Closes #315

…o realm

Give the sandbox a real OAuth2 issuer so the token-protected ledger and
payment journeys are exercisable end to end. Keycloak boots from a static
realm import with a client-credentials demo client whose default scopes
match the services' required authorities, and its hostname is pinned so
every issued token carries the in-network issuer the services validate,
whether the token is requested from inside the network or from the host.
The ledger and payments services point at that issuer. The compose smoke
now proves the whole auth chain: it fetches a token and calls a protected
ledger and payments endpoint expecting success. A path-scoped gitleaks
allowlist covers the documented sandbox demo secret.

Closes #315
@tiana-code tiana-code added this to the v0.2.0 milestone Jun 19, 2026
@tiana-code
tiana-code merged commit d1f4dc3 into main Jun 19, 2026
9 checks passed
@tiana-code
tiana-code deleted the feat/E-06-keycloak-sandbox branch June 19, 2026 21:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

F-06.8 Keycloak in the sandbox compose stack (realm import + client-credentials)

1 participant