Keycloak: Customize the appearance

Easily brand your Keycloak login pages, account console, and emails on Stackhero: set your colors, logo, texts, and even create full custom themes using the built-in online editor.

👋 Welcome to the Stackhero documentation!

Stackhero provides a Keycloak cloud service that makes it simple to deploy a production-ready identity provider in just 2 minutes:

• Unlimited users, realms, and clients
• Supports OpenID Connect, OAuth 2.0, SAML 2.0, social login, LDAP, and Active Directory federation
• Custom domain name with built-in HTTPS for secure access (for example, https://login.your-company.com)
• Custom themes: easily brand your login pages, account console, and emails with an included online editor
• Dedicated email server with SPF, DKIM, and DMARC, so account confirmations and password resets are handled for you
• Built-in PostgreSQL database, with the administration console available on its own closable port
• One-click updates keep your system current without manual intervention

Spend your time building, not configuring: you can try out Stackhero's Keycloak cloud solution in as little as 5 minutes.

Customize the appearance of your Keycloak

Your login page is one of the first things your users see. With Stackhero, you can make it your own in just a few minutes: set your colors, logo, and wording for every language you support. The same approach works for the emails Keycloak sends.

There are two main tools, both included with your service:

• The themes editor, an online file editor where your theme lives.
• Quick Theme, the visual theme designer built into your Keycloak administration console, for choosing colors and branding without editing CSS.

No SSH, no rebuilds, and no redeploys are required.

Open the themes editor

Your service page in the Stackhero dashboard provides a Themes editor URL next to your administration console:

https://your-domain.com:4443/stackhero_themes/

Log in with your Keycloak administrator credentials: the same ones you use for the administration console.

Here are two things to keep in mind:

• The editor runs on the administration port, not the port your applications use. If you close that port in your Stackhero firewall, both the administration console and the editor become inaccessible. Your applications continue authenticating as usual.
• Everything you change here lives on your service disk, is included in your backups, and persists through restarts and updates.

You will find two directories:

Each directory includes a README.md file with up-to-date documentation matching your service version.

Your theme is ready to edit

Open themes/ and you will find a default/ directory. This is your active theme, already in use by your Keycloak instance. There is nothing to select: just edit its files and see your changes reflected immediately.

You do not need prior knowledge of Keycloak themes. Every file inside already lists common settings you may want to change, showing the current Keycloak value as a commented-out example. To update a value, remove the comment mark, adjust the value, and save.

If a line remains commented, Keycloak uses its default value. This ensures your service always matches standard Keycloak behavior, even after updates.

Updating your logo

Open default/login/resources/img/. Inside, you will see the two images currently used on your login page. Upload your own logo using the same file name, keycloak-logo-text.svg, and refresh the login page with Ctrl+F5 (Cmd+Shift+R on macOS).

That is all you need to do. No need to edit files or restart your service: updates are applied as soon as you save. To change the background image, update keycloak-bg-darken.svg in the same folder.

If you prefer to use different file names, you can update the references in default/login/resources/css/stackhero.css under the "Your logo" section.

Setting your colors

In stackhero.css, you will find variables already written with their current values:

:root {
  /* ---------- Colors ---------- */
  /* The buttons */
  /* --pf-v5-global--primary-color--100: #06c; */
  /* The buttons, while hovered */
  /* --pf-v5-global--primary-color--200: #004080; */
  /* The links */
  /* --pf-v5-global--link--Color: #06c; */
  /* The colored line on top of the login box */
  /* --keycloak-card-top-color: #06c; */

To apply a change, remove the comment marks, set your color, save, and reload. That is it.

While you work: Your browser caches theme CSS, images, and scripts for one hour. When iterating, always reload with Ctrl+F5 to see your latest changes. Your visitors will see updates within an hour.

You have full control: the file is plain CSS and loads last, so you can override any style. Use your browser's DevTools (F12) to inspect elements. Keycloak 26 uses the PatternFly design system, so most color variables are named --pf-v5-global--* and can be redefined in :root.

Setting your company name

No theme editing is needed for this. In your administration console, open Realm settings > General and set the Display name. This name appears on login pages and in emails.

Changing texts, in multiple languages

You can update text without touching CSS or HTML. In default/login/messages/messages_en.properties, you will find all login form texts with their default wording. To change a line, remove the #, write your own text, and save:

loginAccountTitle=Sign in to Acme
doLogIn=Sign in
doForgotPassword=I forgot my password

Add files like messages_fr.properties for French or messages_de.properties for German, then enable those languages in the administration console at Realm settings > Localization.

Tip: The Localization tab also has a Realm overrides section, letting you change texts within the console: no file editing or restart required. Use whichever method best fits your workflow.

Branding your emails

Keycloak sends emails for address confirmation, password resets, and user invitations. In default/email/messages/messages_en.properties, you will find the standard subject lines and messages ready to customize:

emailVerificationSubject=Confirm your Acme account
passwordResetSubject=Reset your Acme password

When editing email bodies, remember:

• Keep the {0}, {1}, {2} placeholders (Keycloak will fill them with the link, display name, and delay).
• Escape apostrophes by writing two (don''t).

To override email HTML, copy the template you want from the Keycloak base email theme into default/email/html/, then edit your copy.

Stackhero configures email delivery for you with SPF, DKIM, and DMARC set up. Configure it in Realm settings > Email using the host and port provided on your service page.

If you need to reset your theme

If something goes wrong, you can delete the entire default directory and restart your service. Stackhero will create a fresh default theme, restoring the standard Keycloak appearance.

Your realms, users, and clients are stored in your database and remain unaffected.

Design your theme visually with Quick Theme

In your Keycloak administration console, you will find Quick Theme, Keycloak's visual theme designer. Upload a logo, pick your colors, preview your login and account consoles, and download the finished theme as a .jar file.

To install it, place the file in the themes/ directory using the editor, then restart your service. The .jar is unpacked into a theme directory and the archive is removed:

themes/acme.jar        becomes     themes/acme/

The new theme will appear in Realm settings > Themes. You can continue editing its files manually if you choose.

This method also supports themes built with Keycloakify or themes provided by a designer. Any .jar or .zip containing a theme can be installed this way. If there is already a theme with the same name, the new one is installed as acme-1, ensuring uploads never overwrite your work. If the file is not a theme, it is simply left untouched and Keycloak starts as usual.

One brand per realm: white-label support

Themes are selected per realm in Realm settings > Themes, with options for each page type: login, account, admin, and email. Individual applications can also specify their own login theme in client settings.

If you run multiple brands or offer white-label solutions, use one realm per brand and assign a custom theme to each:

1. In the editor, copy the default directory and rename the copy (for example, acme).
2. Restart your service.
3. In the administration console, open the relevant realm and select acme as its login theme.

Any realm you do not configure continues using your default theme.

Understanding Keycloak theme structure

A theme is a directory containing subdirectories for each type of page:

themes/
  acme/
    login/                             # User sign-in pages
      theme.properties                 # Theme inheritance and CSS includes
      resources/css/stackhero.css      # Your CSS
      resources/img/logo.svg           # Your images
      messages/messages_en.properties  # Your texts
    account/                           # User profile management
    admin/                             # Administration console appearance
    email/                             # Email templates

Themes are inherited from standard Keycloak themes, overriding only what you need. A typical login/theme.properties looks like this:

parent=keycloak.v2
styles=css/styles.css css/stackhero.css

• parent sets the base theme.
• styles lists the CSS files to load. Place your CSS last to ensure your changes take effect.

The styles list replaces the parent theme's list, not extends it. Always include the parent's stylesheet (css/styles.css) or your page will lose its default styling.

You only need FreeMarker templates (.ftl files) if you want to change the HTML structure. For colors, logos, backgrounds, texts, and languages, no template editing is required. For more details, see the Keycloak themes documentation.

Java extensions (providers)

The providers/ directory is for features that themes cannot provide: custom authenticators, user storage, event listeners, or protocol mappers.

Place your .jar file in this directory and restart your service. This restart takes a bit longer (about one minute) as Keycloak rebuilds itself to include the new extension. To remove an extension, delete the file and restart again.

You can also place theme .jar files here, but themes/ is preferred for themes: it requires no rebuild and lets you edit files afterwards.