Theme properties are set in the file <THEME TYPE>/theme.properties in the theme directory.

There are a list of properties that can be used to change the css class used for certain element types. For a list of these properties look at the theme.properties file in the corresponding type of the keycloak theme (themes/keycloak/<THEME TYPE>/theme.properties).

You can also add your own custom properties and use them from custom templates.

When doing so, you can substitute system properties or environment variables by using these formats:

A default value can also be provided in case the system property or the environment variable is not found with ${foo\:defaultValue}.

Here’s an example of what is possible:

javaVersion=${java.version}

unixHome=${env.HOME:Unix home not found}
windowsHome=${env.HOMEPATH:Windows home not found}

You can add one or more stylesheets to a theme.

You can add one or more scripts to a theme.

To make images available to the theme add them to the <THEME TYPE>/resources/img directory of your theme. These can be used from within stylesheets or directly in HTML templates.

For example to add an image to the mytheme copy an image to themes/mytheme/login/resources/img/image.jpg.

You can then use this image from within a custom stylesheet with:

body {
    background-image: url('../img/image.jpg');
    background-size: cover;
}

Or to use directly in HTML templates add the following to a custom HTML template:

<img src="${url.resourcesPath}/img/image.jpg" alt="My image description">

In order to use a custom footer, create a footer.ftl file in your custom login theme with the desired content.

An example for a custom footer.ftl may look like this:

<#macro content>
<#-- footer at the end of the login box -->
<div>
    <ul id="kc-login-footer-links">
        <li><a href="#home">Home</a></li>
        <li><a href="#about">About</a></li>
        <li><a href="#contact">Contact</a></li>
    </ul>
</div>
</#macro>

To make images available to the theme add them to the <THEME TYPE>/email/resources/img directory of your theme. These can be used from within directly in HTML templates.

For example to add an image to the mytheme copy an image to themes/mytheme/email/resources/img/logo.jpg.

To use directly in HTML templates add the following to a custom HTML template:

<img src="${url.resourcesUrl}/img/image.jpg" alt="My image description">

To reference images from common theme resources in email templates, use url.resourcesCommonUrl which provides the full URL (including scheme and host) required by email clients:

<img src="${url.resourcesCommonUrl}/img/logo.png" alt="My logo">

Red Hat build of Keycloak supports adding icons for custom Identity providers, which are displayed on the login screen.

All icons are available on the official website of PatternFly4. Icons for social providers are already defined in base login theme properties (themes/keycloak/login/theme.properties), where you can inspire yourself.

Red Hat build of Keycloak uses Content from freemarker.apache.org is not included.Apache Freemarker templates to generate HTML and render pages.

Although it is possible to create custom templates to change completely how pages are rendered, the recommendation is to leverage the built-in templates as much as possible. The reasons are:

In most cases, you won’t need to change templates to adapt Red Hat build of Keycloak to your needs, but you can override individual templates in your own theme by creating <THEME TYPE>/<TEMPLATE>.ftl. Admin and account console use a single template index.ftl for rendering the application.

For a list of templates in other theme types look at the theme/base/<THEME_TYPE> directory in the JAR file at $KEYCLOAK_HOME/lib/lib/main/org.keycloak.keycloak-themes-<VERSION>.jar.

To edit the subject and contents for emails, for example password recovery email, add a message bundle to the email type of your theme. There are three messages for each email. One for the subject, one for the plain text body and one for the html body.

To see all emails available take a look at themes/base/email/messages/messages_en.properties.

For example to change the password recovery email for the mytheme theme create themes/mytheme/email/messages/messages_en.properties with the following content:

passwordResetSubject=My password recovery
passwordResetBody=Reset password link: {0}
passwordResetBodyHtml=<a href="{0}">Reset password</a>

By default the theme configured for the realm is used, with the exception of clients being able to override the login theme. This behavior can be changed through the Theme Selector SPI.

This could be used to select different themes for desktop and mobile devices by looking at the user agent header, for example.

To create a custom theme selector you need to implement ThemeSelectorProviderFactory and ThemeSelectorProvider.

When implementing custom providers there may often be a need to add additional templates, resources and messages bundles.

The easiest way to load additional theme resources is to create a JAR with templates in theme-resources/templates resources in theme-resources/resources and messages bundles in theme-resources/messages.

If you want a more flexible way to load templates and resources that can be achieved through the ThemeResourceSPI. By implementing ThemeResourceProviderFactory and ThemeResourceProvider you can decide exactly how to load templates and resources.

By default, the locale is selected using the DefaultLocaleSelectorProvider which implements the LocaleSelectorProvider interface. English is the default language when internationalization is disabled.

With internationalization enabled, the locale is resolved according to the logic described in the Content from www.keycloak.org is not included.Server Administration documentation.

This behavior can be changed through the LocaleSelectorSPI by implementing the LocaleSelectorProvider and LocaleSelectorProviderFactory.

The LocaleSelectorProvider interface has a single method, resolveLocale, which must return a locale given a RealmModel and a nullable UserModel. The actual request is available from the KeycloakSession#getContext method.

Custom implementations can extend the DefaultLocaleSelectorProvider in order to reuse parts of the default behavior. For example to ignore the Accept-Language request header, a custom implementation could extend the default provider, override it’s getAcceptLanguageHeaderLocale, and return a null value. As a result the locale selection will fall back on the realm’s default language.