Theming a single Keycloak realm is simple. The moment you multiply that by many tenants, new problems appear that don’t exist at small scale.

What is a Keycloak theme?

A theme in Keycloak is a bundle of templates, images, and stylesheets that controls how a particular part of Keycloak looks and behaves. Keycloak actually has four separate theme types that can each be set independently: the login theme (the sign-in and registration pages), the account theme (the self-service “my account” console), the email theme (password reset and verification emails), and the admin theme (the administrator console itself).

What “at scale” actually means here

Theming one realm for one brand is a one-time design task. Theming a platform where each of two hundred tenants wants a distinct logo, color palette, and sometimes even different form fields, turns that same task into an ongoing content-management problem: how do you add a theme for tenant 201 without touching tenant 1 through 200, and without every theme secretly duplicating the same base CSS and templates over and over again?

Keycloak’s theming engine is built from a small number of pieces that repeat consistently across every theme you create.

Theme inheritance — the key to avoiding duplication

Every custom theme can declare a parent theme in its theme.properties file, most commonly Keycloak’s built-in base or keycloak theme. Anything the custom theme doesn’t explicitly override — templates, messages, styles — falls back to the parent automatically. This inheritance chain is exactly what makes theming scale: a shared “tenant-base” theme can hold every common template and script once, and each individual tenant theme only needs to override a logo, a color variable, or a handful of styles.

graph TD
    A[keycloak base theme] --> B[tenant-base theme]
    B --> C[acme-theme]
    B --> D[globex-theme]
    B --> E[initech-theme]
    C -->|overrides| C1[logo.svg, primary-color]
    D -->|overrides| D1[logo.svg, primary-color]
    E -->|overrides| E1[logo.svg, primary-color]
        

Every page Keycloak renders goes through a lookup step to decide which theme’s files to actually use.

The default lookup order

By default, Keycloak resolves the theme to use for a given request from the realm’s configuration — each realm has its own loginTheme, accountTheme, emailTheme, and adminTheme settings. A client application registered within that realm can also override just the login theme for itself, which is what allows two different applications in the same realm to present different-looking login pages if needed.

Going beyond static configuration: the Theme Selector SPI

For situations more advanced than “one theme per realm,” Keycloak exposes a Service Provider Interface specifically for this decision: the Theme Selector SPI. A custom implementation of this SPI can inspect the incoming request — the hostname, a request header, the user’s device — and dynamically decide which theme to serve, overriding the realm’s static setting entirely. This is how some platforms serve a different look for mobile browsers than desktop, or resolve theming from a custom domain rather than from realm configuration alone.

sequenceDiagram
    autonumber
    participant U as Browser
    participant KC as Keycloak
    participant TS as Theme Selector
    U->>KC: GET /realms/acme/login
    KC->>TS: Resolve theme for this request
    TS-->>KC: "acme-theme"
    KC->>KC: Load acme-theme, falling back to parent theme for anything missing
    KC-->>U: Rendered login page
        

Theme caching

Once a theme’s files are resolved, Keycloak caches parsed templates and resource lookups in memory for performance, since re-reading files from disk on every single login request would be wasteful at any real traffic volume. This caching is exactly why a theme change sometimes doesn’t appear to take effect immediately in a running production server — the cache needs to expire or be explicitly cleared before the new files are picked up.

Rolling out a new tenant’s look, or updating an existing one, follows a repeatable sequence once a platform is operating at scale.

Templates can execute logic, not just display markup

Keycloak’s login and account themes are built on the FreeMarker templating engine, which means a theme isn’t purely passive HTML — it can include logic and reference request data. A theme sourced from an untrusted or poorly reviewed party, especially in a platform that lets tenants submit their own custom templates rather than just a logo and colors, needs the same code-review scrutiny as any other server-side code, since a malicious template could attempt to leak session data or manipulate the rendered page in unintended ways.

Isolating tenant theme files from each other

Just as realm data is isolated per tenant, theme files should be organized so that one tenant’s theme folder can never accidentally reference or overwrite another’s — particularly important in automated pipelines that generate new theme folders programmatically, where a naming collision or a templating bug could serve the wrong tenant’s branding to the wrong login page.

The admin theme deserves separate attention

Because the admin theme controls the Keycloak administrator console itself, it’s generally kept as Keycloak’s own built-in theme rather than customized per tenant, both to reduce the surface area needing security review and because administrators — unlike end users — are not the audience branding is meant to persuade.

Watching for missing or broken theme assets

A tenant theme referencing an image or stylesheet that failed to deploy correctly typically surfaces as a 404 on a specific resource path rather than a full page failure — the login form still renders, just without its branding. Tracking 404 rates specifically on theme resource paths catches these partial failures long before a tenant notices and complains.

Theme cache behavior under load

Since theme lookups are cached for performance, monitoring cache hit rates and template render times gives visibility into whether the theming layer is behaving efficiently as tenant count and login volume both grow — a sudden drop in cache effectiveness after adding a batch of new tenants is worth investigating before it becomes a user-facing latency problem.

Common mistakes to avoid

Beyond duplicated theme folders and manual deployment, teams frequently forget that changing the shared base theme’s structure — not just its styling — can silently break tenant overrides that assumed a particular template layout. It’s also easy to overlook the email theme entirely while focused on the login page; a beautifully branded login experience followed by a generic, unbranded password-reset email undermines the consistency the whole effort was meant to achieve.

Yes. Theme assignment is just a configuration value on the realm, so multiple realms can point at the same theme name if their branding is meant to be identical, with no extra setup required.

No. Assigning a different theme to each realm’s login, account, and email settings is sufficient for the common case of one distinct look per tenant. The Theme Selector SPI is only needed when the choice of theme depends on something beyond the realm itself, such as device type or a custom domain.

Keycloak caches theme templates and resources for performance. Depending on your environment’s caching configuration, a change may need the cache explicitly cleared, or the server restarted, before it becomes visible.

Only with careful review. Templates can include logic, not just static markup, so tenant-submitted templates carry more risk than tenant-submitted images or color values and should be reviewed with the same rigor as any other server-side code.

Not necessarily. Many platforms fully customize the login theme, lightly customize the email theme for brand consistency, and leave the account and admin themes on shared defaults, since those are seen far less often and by a narrower audience.

Theming at scale in Keycloak is the practice of giving every tenant on a shared deployment a distinct, on-brand login, account, and email experience without multiplying design and maintenance work by the number of tenants. It relies on Keycloak’s theme inheritance model to keep shared structure in one place, on per-realm (and optionally per-client) theme assignment to route each tenant to its own look, and — for more advanced needs — on the Theme Selector SPI to make that routing dynamic. The pattern that scales well keeps each tenant’s own theme as thin as possible, automates its deployment alongside realm provisioning, and treats theme files with the same version-control and review discipline as any other production code.