Keycloak in Docker #3 – How to customise Keycloak themes

feature image

Keycloak allows us to customise its themes. This enables us to provide a user interface that remains consistent across all of our applications, ensuring a better user experience for everyone.

Prerequisites

Disable theme caching

The Keycloak documentation recommends disabling the cache for themes while working on creating our custom theme:

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 Keycloak. To do this edit standalone.xml. (…) Remember to re-enable caching in production as it will significantly impact performance.

https://www.keycloak.org/docs/latest/server_development/#creating-a-theme

Therefore, we’re going to write a script that disables caching themes and run it as a startup script for our container. First, I’m going to add the backend/docker/keycloak/scripts/disable-theme-cache.cli file to my repository:

Next, I’ll provide the script as a volume for the container’s startup-scripts directory:

You can find the work presented in this section in the 37ab28cd42b8fe84ad9d09bf0af2782120418e98 commit.

Customising

A Keycloak theme contains styles and assets for different groups of pages – called types in the documentation:

A theme can provide one or more types to customise different aspects of Keycloak. The types available are:

Account – used to style user profile views;

Admin – with styles for the admin UI;

Email – for styling emails;

Login – used to customise login forms (login, register, forgot password);

Welcome – the Welcome page.

https://www.keycloak.org/docs/latest/server_development/#theme-types

For the sake of simplicity, I’m going to customise only two types – Login and Account. In the first place, I’m going to create an empty directory for my theme:

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.

https://www.keycloak.org/docs/latest/server_development/#creating-a-theme

Comsequently, I’m going to create the backend/docker/keycloak/themes/custom directory as I want to name my theme custom. Furthermore, I’m going to mount it as a volume in my keycloak service:

As a result, we’ll see my custom theme among other Keycloak themes after restarting the service:

Keycloak themes directory with the custom theme

Customise Keycloak theme for the login type

Of course, the custom theme is still empty and we can’t apply it. In other words, all Keycloak pages use default styles. We’re going to start our customisation from the login type. Visit: http://localhost:9900/auth/realms/efficient-mvp/account link to examine the standard Keycloak login type:

default login page for keycloak

I’m going to create the login folder inside the custom directory. However, I’m not going to fabricate my theme completely from scratch. I’ll follow the documentation on creating a new theme and extend the Keycloak theme:

Most likely you will want to extend the Keycloak 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 Keycloak theme primarily contains images and stylesheets.

https://www.keycloak.org/docs/latest/server_development/#creating-a-theme

For reference, this is the structure of the login folder that we’re going to create:

directory tree for custom theme for the login type

Change background image

First, I want to use a different picture as a page background. Therefore, I’m going to create the custom/login/resources/img folder and download the new picture there (pexels-pixabay-358312.jpg).

Change login styles

Next, I’m going to override some styles in the custom/login/resources/styles.css:

Generally speaking, my styles replace the default picture and provide a gradient as a fallback background. Moreover, I’m changing the primary colour (providing the lighter and darker shades) and the colour and text decoration of links for the hover pseudo-class. Last but not least, I’m resetting the default primary colour for forms as it would override the one I set in the :root section.

Configure the custom login type

In order to include our styles in the theme, we need to create the custom/login/theme.properties file. Each type has to have this file as the source of its configuration. Since we’re extending the login type from the Keycloak theme, let’s see the theme.properties file for our parent as a reference:

original properties for the login type in the keycloak theme

As we can see, we definitely need to override the parent property for our theme. We also can’t forget to include the Keycloak stylesheets before providing our own:

To include the styles from the parent theme you need to load the styles from that theme as well.

https://www.keycloak.org/docs/latest/server_development/#stylesheets

The resulting theme.properties file for the login type for the custom theme looks as follow:

Enable the customised type

Restart the service so that the volume with our custom theme is mounted (if you haven’t restarted it after creating the volume). Login as admin to the admin panel (http://localhost:9900/auth/) and choose the custom theme as a value for the Login Theme property in the realm settings:

enable custom login type for Keycloak theme

Verify changes of the login type

Now, visit the: http://localhost:9900/auth/realms/efficient-mvp/account page and verify that the new theme is used instead of the default one:

customose Keycloak themes for the login pages
Background photo by Pixabay from Pexels

You can see the work presented in this article in the e56bc36f6fa2e6776bdddd4403ea51ecfa185845 commit.

Customise Keycloak theme for the account type

You can see the default keycloak.v2 theme used for the account type on the image below:

default user account page

To keep this section concise, I’m not going to include the content of the default keycloak.v2 theme. You can find it in the keycloak container under the opt/jboss/keycloak/themes/keycloak.v2 path:

default directory tree for theme for the account type

For reference, this is the structure of the account folder that we’re going to create:

directory tree for custom theme for account type

On top of customising some styles in the layout.css file, I’m going to provide my own logo and favicon.

Change account styles

Since I’m going to extend the keycloak.v2 theme I’ll mirror its directory structure. First, I’m going to override some styles in my custom/account/resources/public/layout.css:

In genral, I’m going to change the primary colour, unset a keycloak class that would override it and update button styles. Please note that we have disabled theme caching so trying different styles won’t consume much of your time 🙂

Configure the custom account type

For the configuration extending the keycloak.v2 theme I’m going to provide the following theme.properties file:

That’s all we need to do to prepare the account type for our custom theme.

Enable the customised type

Again, login as admin to the admin panel (http://localhost:9900/auth/) and choose the custom theme as a value for the Accont Theme property in the realm settings:

activate custom theme for the account type

Verify changes of the account type

Now, visit the: http://localhost:9900/auth/realms/efficient-mvp/account page, login as one of the realm users and verify that the new theme is used instead of the default one:

customise Keycloak themes for the account pages

You can see the work presented in this article in the 904d132c49bf795c5aa0fc32a8c04207f3adf0b9 commit.

Learn more on how to customise Keycloak themes

Photo by Ezekixl Akinnewu from Pexels

Leave a Reply

Your email address will not be published. Required fields are marked *