Chapter 3. Themes

A theme can provide one or more types to customize different aspects of Red Hat Single Sign-On. The types available are:

All theme types, except welcome, are configured through the Admin Console. To change the theme used for a realm open the Admin Console, select your realm from the drop-down box in the top left corner. Under Realm Settings click Themes.

To change the welcome theme you need to edit standalone.xml, standalone-ha.xml, or domain.xml. For more information on where these files reside see the Server Installation and Configuration Guide.

Add welcomeTheme to the theme element, for example:

<theme>
    ...
    <welcomeTheme>custom-theme</welcomeTheme>
    ...
</theme>

If the server is running you need to restart the server for the changes to the welcome theme to take effect.

Red Hat Single Sign-On comes bundled with default themes in the server’s root themes directory. To simplify upgrading you should not edit the bundled themes directly. Instead create your own theme that extends one of the bundled themes.

A theme consists of:

Unless you plan to replace every single page you should extend another theme. Most likely you will want to extend the Red Hat Single Sign-On theme, but you could also consider extending the base theme if you are significantly changing the look and feel of the pages. The base theme primarily consists of HTML templates and message bundles, while the Red Hat Single Sign-On theme primarily contains images and stylesheets.

When extending a theme you can override individual resources (templates, stylesheets, etc.). If you decide to override HTML templates bear in mind that you may need to update your custom template when upgrading to a new release.

While creating a theme it’s a good idea to disable caching as this makes it possible to edit theme resources directly from the themes directory without restarting Red Hat Single Sign-On. To do this edit standalone.xml. For theme set staticMaxAge to -1 and both cacheTemplates and cacheThemes to false:

<theme>
    <staticMaxAge>-1</staticMaxAge>
    <cacheThemes>false</cacheThemes>
    <cacheTemplates>false</cacheTemplates>
    ...
</theme>

Remember to re-enable caching in production as it will significantly impact performance.

To create a new theme start by creating a new directory in the themes directory. The name of the directory becomes the name of the theme. For example to create a theme called mytheme create the directory themes/mytheme.

Inside the theme directory create a directory for each of the types your theme is going to provide. For example to add the login type to the mytheme theme create the directory themes/mytheme/login.

For each type create a file theme.properties which allows setting some configuration for the theme. For example to configure the theme themes/mytheme/login that we just created to extend the base theme and import some common resources create the file themes/mytheme/login/theme.properties with following contents:

parent=base
import=common/keycloak

You have now created a theme with support for the login type. To check that it works open the admin console. Select your realm and click on Themes. For Login Theme select mytheme and click Save. Then open the login page for the realm.

You can do this either by login through your application or by opening the Account Management console (/realms/{realm name}/account).

To see the effect of changing the parent theme, set parent=keycloak in theme.properties and refresh the login page.

.login-pf body {
    background: DimGrey none;
}

styles=css/styles.css

styles=node_modules/patternfly/dist/css/patternfly.css node_modules/patternfly/dist/css/patternfly-additions.css lib/zocial/zocial.css css/login.css css/styles.css

alert('Hello');

scripts=js/script.js

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

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

usernameOrEmail=Your Username

usernameOrEmail=Brukernavn
password=Passord

locales=en,no

locale_no=Norsk

# encoding: UTF-8
usernameOrEmail=....

<#import "template.ftl" as layout>
<h1>HELLO WORLD!</h1>
...

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

Themes can be deployed to Red Hat Single Sign-On by copying the theme directory to themes or it can be deployed as an archive. During development you can copy the theme to the themes directory, but in production you may want to consider using an archive. An archive makes it simpler to have a versioned copy of the theme, especially when you have multiple instances of Red Hat Single Sign-On for example with clustering.

To deploy a theme as an archive you need to create a JAR archive with the theme resources. You also need to add a file META-INF/keycloak-themes.json to the archive that lists the available themes in the archive as well as what types each theme provides.

For example for the mytheme theme create mytheme.jar with the contents:

The contents of META-INF/keycloak-themes.json in this case would be:

{
    "themes": [{
        "name" : "mytheme",
        "types": [ "login", "email" ]
    }]
}

A single archive can contain multiple themes and each theme can support one or more types.

To deploy the archive to Red Hat Single Sign-On simply drop it into the standalone/deployments/ directory of Red Hat Single Sign-On and it will be automatically loaded.

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.

Follow the steps in Service Provider Interfaces for more details on how to create and deploy a custom provider.

When implementing custom providers in Red Hat Single Sign-On there may often be a need to add additional templates and resources.

The easiest way to load additional theme resources is to create a JAR with templates in theme-resources/templates and resources in theme-resources/resources and drop it into the standalone/deployments/ directory of Red Hat Single Sign-On.

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.

Follow the steps in Service Provider Interfaces for more details on how to create and deploy a custom provider.

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 in the following priority:

This behaviour 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 behaviour. 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 realms’s default language.

Follow the steps in Service Provider Interfaces for more details on how to create and deploy a custom provider.