Chapter 3. Themes

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">

Text in the templates is loaded from message bundles. A theme that extends another theme will inherit all messages from the parent’s message bundle and you can override individual messages by adding <THEME TYPE>/messages/messages_en.properties to your theme.

For example to replace Username on the login form with Your Username for the mytheme create the file themes/mytheme/login/messages/messages_en.properties with the following content:

usernameOrEmail=Your Username

Within a message values like {0} and {1} are replaced with arguments when the message is used. For example {0} in Log in to {0} is replaced with the name of the realm.

Texts of these message bundles can be overwritten by realm-specific values. The realm-specific values are manageable via UI and API.

By default, message properties files should be encoded using UTF-8. Keycloak falls back to ISO-8859-1 handling if it can’t read the contents as UTF-8. Unicode characters can be escaped as described in Java’s documentation for PropertyResourceBundle. Previous versions of Keycloak supported specifying the encoding in the first line with a comment like # encoding: UTF-8, which is no longer supported.

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 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>