EPIC: replace the bespoke auth runtime with Keycloak and retain only the custom theme

[Xore]

Outcome

Replace the bespoke Go authentication runtime with Keycloak in one hard cutover. Keycloak owns identity, credentials, sessions, MFA/passkeys, recovery, authorization policy, and protocol behavior.

Xore/auth-backend retains only a supported custom Keycloak theme (themes/apiary), based on the vendored xore/theme system, reproducing the current auth-backend look and feel. Updated 2026-08-09: Keycloak deployment/realm configuration and validation ended up owned by Xore/APIARY instead, not here -- see "Cross-repository dependency" below for the reconciled split.

Fixed decisions

• This is a greenfield identity launch. All administrators and users are created fresh in Keycloak.
• Do not import, preserve, synchronize, export, or restore legacy users, passwords, MFA seeds, recovery codes, passkeys, roles, or sessions.
• Do not keep the Go service as a forward-auth adapter or fallback.
• Do not create a parallel custom CSS layer. Shared tokens, components, and assets live in xore/theme.
• Cutover is one-way. Recovery procedures restore the new Keycloak system, not the old authentication runtime.
• The new system must work in every supported functional path before production cutover.
• The current visual experience must remain recognizable and materially equivalent across all enabled Keycloak flows.

Workstreams

• Phase 0: define the Keycloak target architecture, ownership boundary, and threat model #88 — target architecture, ownership boundary, and threat model (closed 2026-08-09, superseded -- see below)
• Phase 1: build the production Keycloak and PostgreSQL deployment baseline #89 — production Keycloak and PostgreSQL baseline (closed 2026-08-09, superseded -- see below)
• Phase 2: manage the Keycloak realm, clients, roles, groups, and authentication policies as code #90 — realm, clients, roles, groups, and policies as code (closed 2026-08-09, superseded -- see below)
• Phase 3: build the xore/theme-based Keycloak theme to match the current auth-backend #91 — xore/theme-based custom Keycloak theme with visual parity (still open, in progress)
• Phase 4: configure Keycloak security hardening, audit, observability, backup, and upgrade operations #93 — security hardening, audit, observability, backup, and upgrade operations (closed 2026-08-09, superseded -- see below)
• Phase 5 TESTING: implement automated Keycloak realm, theme, user-provisioning, and security validation #94 — automated realm, theme, fresh-user, and security testing (closed 2026-08-09, superseded -- see below)
• Phase 6 VALIDATION: validate every flow, hard-cut over, and retire the bespoke Go auth service #95 — production-shaped validation, hard cutover, and removal of the Go runtime (closed 2026-08-09, superseded -- see below)

Cross-repository dependency

• APIARY epic: EPIC: hard-cut over every APIARY authentication path to Keycloak APIARY#986
• APIARY milestone: https://github.com/Xore/APIARY/milestone/1
• APIARY must switch the dashboard and every protected UI to Keycloak.
• Kibana, EveBox, and Arkime require explicit end-to-end authorized, denied, bypass, logout, deep-link, API/download, and outage evidence.
• Updated 2026-08-09, reconciled with actual ownership: this epic's own "Outcome" originally planned for Xore/auth-backend to retain "declarative Keycloak deployment/realm configuration, validation tests, and a supported custom Keycloak theme." That's not what happened. Xore/APIARY owns Keycloak deployment end to end -- the realm template, the Dockge stack compose file, VPS Traefik/gateway routing, install/deploy automation, and the operator runbook, all live there (docs/KEYCLOAK-OPERATIONS.md is the canonical reference). Xore/auth-backend owns exactly one thing going forward: the presentation-only themes/apiary Keycloak theme, checked out read-only into the APIARY deployment at build/install time (.github/workflows/deploy.yml's dedicated checkout step, and scripts/install-homeserver.sh's equivalent for a from-scratch install). Workstreams Phase 1: build the production Keycloak and PostgreSQL deployment baseline #89/Phase 2: manage the Keycloak realm, clients, roles, groups, and authentication policies as code #90/Phase 4: configure Keycloak security hardening, audit, observability, backup, and upgrade operations #93/Phase 5 TESTING: implement automated Keycloak realm, theme, user-provisioning, and security validation #94 above should be read with that narrower scope in mind, or migrated to APIARY's own workstream tracking if their remaining work is APIARY-side.

Verified completed work (audited 2026-08-09)

• PR Narrow auth-backend to Keycloak theme ownership #97 promoted the presentation-only Keycloak theme tree to main.
• The active tree contains no bespoke Go auth runtime, Redis coupling, legacy Compose deployment, old auth routes, or fallback adapter.
• CI enforces the theme-only repository boundary and scans for leaked operational secrets.
• APIARY is documented as the sole owner of Keycloak runtime, realm, clients, policy, routing, backups, and validation.
• The theme inherits keycloak.v2 and consumes a pinned vendored xore/theme stylesheet.
• Visual and interaction parity is not complete: Phase 3: build the xore/theme-based Keycloak theme to match the current auth-backend #91 and children Keycloak theme doesn't match APIARY branding: hardcoded 'xore//auth' header text, stock demo artwork, stale pre-rebrand typography pin, no favicon #98-Theme parity: replace the split demo with the historical centered login experience #104 remain the authoritative work.
• Full enabled-flow screenshot, DOM, keyboard, responsive, accessibility, and pinned-Keycloak compatibility evidence is still outstanding.

Epic completion gates

• Empty environment builds a working Keycloak/PostgreSQL/realm/theme release deterministically.
• Fresh administrator and user provisioning, password, recovery, TOTP, WebAuthn/passkey, logout, revocation, role, and session paths pass.
• Security, audit, observability, key rotation, outage, and new-system backup/restore paths pass.
• Screenshot and interaction evidence confirms all enabled Keycloak pages match the current auth-backend look and feel using xore/theme.
• APIARY dashboard and every protected hostname pass functional and authorization validation.
• Bespoke Go auth runtime, Redis coupling, old routes, old secrets, and legacy identity paths are absent from the active auth-backend/main tree after cutover.

Milestone: https://github.com/Xore/auth-backend/milestone/1

[Xore]

Status update — Keycloak hard cutover

The implementation branch is now theme-only and ready to become the repository default line.

Completed:

• Removed the bespoke Go auth runtime, Redis coupling, legacy deployment files, and fallback path from the branch tree.
• Repository boundary now permits only the supported themes/apiary package plus documentation and validation automation.
• Added the Keycloak v2 theme declaration and pinned vendored xore/theme CSS.
• Added a first full Xore-style split authentication layout, responsive artwork, form/error styling, and reduced-motion handling.
• APIARY owns the Dockge Keycloak/PostgreSQL deployment, realm, clients, gateways, backups, and operational runbook.
• Theme validation and secret scanning pass on PR Narrow auth-backend to Keycloak theme ownership #97.

Current follow-up:

• Keycloak theme doesn't match APIARY branding: hardcoded 'xore//auth' header text, stock demo artwork, stale pre-rebrand typography pin, no favicon #98 tracks the remaining branding/parity gap discovered during review: replace temporary generic auth branding/artwork details with approved APIARY assets and complete visual comparison across every Keycloak flow.
• Full password-update, TOTP, WebAuthn, recovery, informational/error, mobile, and screenshot-matrix evidence remains required before closing Phase 3: build the xore/theme-based Keycloak theme to match the current auth-backend #91/Phase 5 TESTING: implement automated Keycloak realm, theme, user-provisioning, and security validation #94/Phase 6 VALIDATION: validate every flow, hard-cut over, and retire the bespoke Go auth service #95 and this epic.

Repository cutover:

• agent/keycloak-phase-0 is a clean descendant of main; PR Narrow auth-backend to Keycloak theme ownership #97 is being promoted so its theme-only tree becomes main. The pre-Keycloak implementation remains only in Git history, not as a runtime, fallback, or backup branch.

[Xore]

Repository promotion complete: PR #97 merged as 313c133; the theme-only Keycloak tree is now main, the feature branch was deleted, and the former bespoke implementation is retained only in Git history. No legacy runtime or fallback files exist in the current branch.

[Xore]

Ultracode Keycloak-theme review — issue filed

Cross-posting from the APIARY side (see Xore/APIARY#986's own index comment for the full picture across both repos): a review of this migration found the Keycloak login/account theme in this repo doesn't currently match APIARY's actual branding.

• Keycloak theme doesn't match APIARY branding: hardcoded 'xore//auth' header text, stock demo artwork, stale pre-rebrand typography pin, no favicon #98 (open, not yet fixed) — four compounding problems: the login header is hardcoded to the legacy xore//auth product name (actively hiding the real realm displayName, "APIARY"); the background artwork is Xore/theme's own generic stock demo illustration, not APIARY brand art; theme.lock is pinned to a commit that predates the upstream typography rebrand (Fira Sans/Space Grotesk/Fira Code), so the login page still renders in the old Inter/Iowan Old Style fonts while the dashboard right after login already uses the new ones; and there's no favicon override, so login/account tabs show Keycloak's stock icon instead of APIARY's.

Full evidence and a suggested fix per item are in #98 itself.

[Xore]

Update: #98 (referenced above as "open, not yet fixed") is now closed -- resolved by PR #105 ("Phase 3 theme parity: historical centered login, branding, compat pin, interaction layer"), which landed all four items (header text, background artwork, typography pin, favicon).

Leaving this EPIC open -- mirrors Xore/APIARY#986's own status, which still has real open workstreams (#976, #979, #982, #984 on the APIARY side).