You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Login themes: near-term FreeMarker extensibility vs longer-term Authentication UI API
#54628
Login customization is painful today: templates are duplicated, customization points are inconsistent, and many custom themes copy whole pages to change small parts. That makes upgrades hard and causes fixes to drift between Base and keycloak.vX.
This discussion proposes a two-track direction: improve the current FreeMarker + PatternFly stack in the near term, and explore a headless Authentication UI API as a longer-term option.
Track 1 - Current server-side rendering (FreeMarker + PatternFly)
We cannot drop FreeMarker right away. Many users already rely on it, and it is tightly coupled to the Java codebase (flows, required actions, authenticators).
For Keycloak 27 and the near term, the practical approach looks like:
Keep FreeMarker as the login rendering model.
Invest in a clearer Base login theme plus keycloak.vX themes on PatternFly.
Make common branding customizable without copying entire pages.
Prefer Admin UI tooling (Quick Theme and similar) so many customers never need to edit .ftl files directly.
Concrete extensibility ideas
Template regions
Today, only the footer can be customized by providing a specific .ftl without touching template.ftl. We could add:
header.ftl for custom headers
optionally header-side.ftl for content beside the login form (PatternFly 6 supports this well — logo, client description, marketing content)
Quick Theme / Admin UI
If header/footer/(side) content can be configured in the Admin UI:
customers may not need custom .ftl files at all
uploaded images could be referenced from those regions
Base components + theme properties
Template regions help branding, but they are not enough on their own. Many page copies exist only to change field/button markup. Moving reusable field macros into Base, with CSS classes driven by theme properties, would:
reduce duplicated pages in keycloak.vX
let custom themes override one component (or a few properties) instead of whole pages like login.ftl / register.ftl
make the next PatternFly upgrade mostly a properties/CSS change rather than another full template fork
Removing obsolete login themes (for example Login v1) also simplifies Base, because Base no longer has to preserve legacy markup forever.
Suggested near-term sequencing
Remove obsolete login themes where already planned.
Improve Base: reusable field macros + properties, plus header/footer/(side) includes.
Land login v3 / PatternFly 6 on top of that thinner Base (fewer page copies).
Wire Quick Theme so header/footer/side (and images) can be set without FreeMarker.
Migration guidance and consistent release documentation for theme changes should ship with that work.
Non-goals for track 1
Replacing FreeMarker entirely
Switching away from PatternFly
Changing other theme types (account/admin) as part of this milestone
Track 2 - Longer-term client-side / headless Authentication UI API
There is clear demand for login UX beyond simple theming: fully custom UIs, SPA shells, and framework-agnostic clients.
A longer-term direction could be an Authentication UI API between clients and the server:
endpoints that describe what the current step expects/requires (metadata)
server exchanges data as JSON rather than rendering HTML
clients build their own pages/forms and post JSON back
Keycloak could ship a JS/TS helper library for common pieces
That would make login customization a protocol/API concern instead of a theme concern.
Why this is not the near-term plan
It touches a lot of surface area: authentication flows, required actions, session/CSRF, error mapping, application-initiated actions, progressive flows, and more. It is valuable, but not quickly feasible as a replacement for FreeMarker themes.
Proposal: keep this as a separate future epic, not as a checkbox under “make login themes easier to extend.” Track 1 should remain deliverable without waiting on track 2.
Track 1 reduces upgrade pain for the majority of theme users. Track 2 is the path for users who outgrow theming entirely. Work on track 1 can still inform track 2 later (page inventory, context shape, required fields/messages), but track 2 should not block shipping Base extensibility and PatternFly 6 login.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Context
Related milestone: #54544
Login customization is painful today: templates are duplicated, customization points are inconsistent, and many custom themes copy whole pages to change small parts. That makes upgrades hard and causes fixes to drift between Base and
keycloak.vX.This discussion proposes a two-track direction: improve the current FreeMarker + PatternFly stack in the near term, and explore a headless Authentication UI API as a longer-term option.
Track 1 - Current server-side rendering (FreeMarker + PatternFly)
We cannot drop FreeMarker right away. Many users already rely on it, and it is tightly coupled to the Java codebase (flows, required actions, authenticators).
For Keycloak 27 and the near term, the practical approach looks like:
keycloak.vXthemes on PatternFly..ftlfiles directly.Concrete extensibility ideas
Template regions
Today, only the footer can be customized by providing a specific
.ftlwithout touchingtemplate.ftl. We could add:header.ftlfor custom headersheader-side.ftlfor content beside the login form (PatternFly 6 supports this well — logo, client description, marketing content)Quick Theme / Admin UI
If header/footer/(side) content can be configured in the Admin UI:
.ftlfiles at allBase components + theme properties
Template regions help branding, but they are not enough on their own. Many page copies exist only to change field/button markup. Moving reusable field macros into Base, with CSS classes driven by theme properties, would:
keycloak.vXlogin.ftl/register.ftlRemoving obsolete login themes (for example Login v1) also simplifies Base, because Base no longer has to preserve legacy markup forever.
Suggested near-term sequencing
Migration guidance and consistent release documentation for theme changes should ship with that work.
Non-goals for track 1
Track 2 - Longer-term client-side / headless Authentication UI API
There is clear demand for login UX beyond simple theming: fully custom UIs, SPA shells, and framework-agnostic clients.
A longer-term direction could be an Authentication UI API between clients and the server:
That would make login customization a protocol/API concern instead of a theme concern.
Why this is not the near-term plan
It touches a lot of surface area: authentication flows, required actions, session/CSRF, error mapping, application-initiated actions, progressive flows, and more. It is valuable, but not quickly feasible as a replacement for FreeMarker themes.
Proposal: keep this as a separate future epic, not as a checkbox under “make login themes easier to extend.” Track 1 should remain deliverable without waiting on track 2.
How the tracks relate
LoginFormsProvider+ FreeMarker/theme modelTrack 1 reduces upgrade pain for the majority of theme users. Track 2 is the path for users who outgrow theming entirely. Work on track 1 can still inform track 2 later (page inventory, context shape, required fields/messages), but track 2 should not block shipping Base extensibility and PatternFly 6 login.
Questions for discussion
header.ftl/header-side.ftl(+ Quick Theme wiring) the right first customization hooks, together with Base field macros?base-legacy(or similar) be an explicit migration target when login v3 becomes default?Feedback welcome, especially from people maintaining custom login themes or theme tooling.
All reactions