Customizing Keycloak themes

When you are integrating Keycloak with your web application, you may think to customize the default Keycloak theme. Keycloak templates are written using FreeMarker templates. You can customize it very easily. 

First, you need to login as admin.

Go to Realm settings and select the Themes tab.

Now you can see some options about themes and language support. There are several options to change the default theme. It can be changed to the Login theme, Account theme, the Admin console theme… etc.. By default, two themes are provided (base and keycloak) for each option.

Before adding new themes

• Before adding new themes, some configurations need to be done.
• According to Keycloak documentation theme caching and template caching can be disabled. This allows the user to edit themes without restarting the Keycloak server.
• To change this, go to the standalone directory and then go inside the configuration.

                    Keycloak -> standalone -> configuration -> standalone.xml

• There are several files, but the only standalone.xml should be changed. 
• Please change it as follows

But please remember to re-enable it on production 

Add new themes

• New themes can be added where the Keycloak server is installed.
• Basically, the Keycloak server looks like this. Please refer to the following image.

New themes should be added to the themes directory.

• By default, three Themes are available (base, keycloak, and keycloak-preview)
• The base theme consists of basic template files for each page without styles. It acts as a parent.

• Keycloak theme extends the Base theme and it has some specific styles.
• The documentation says not to edit preloaded themes, instead, create your own theme and extend the base theme according to your requirements.
• You can change themes for an account, admin, email, login, and welcome pages. The above directory names should be exactly the same. You cannot change those directory names.

Create your own theme

Let’s create a new theme called “myTheme”. In this theme, I am going to customize the login page. Create a folder inside the Theme directory and that folder name becomes the name of the theme. Here is the flow. Please use the exact words for directories and files.

1. Go to Keycloak then themes
2. Create a directory called “myTheme”. This will be the theme name.
3. Go to myTheme directory
4. Create a directory called login. This specifies that you are going to change the login theme. 
5. Go inside of login directory
6. Create a directory called resources and create a property file called theme.properties. The resources directory contains all resources files such as styles and images. 
7. theme.properties file contains property definitions.
8. Go inside the resources directory and create two directories called css and img. 

What is the theme.property file

theme.property file consists of some basic configuration things.

1. Parent class (parent=keycloak) 
2. Where style sheets are located (styles=css/styles.css) 
3. Keycloak tags related to Bootstrap tags (kcHtmlClass=login-pf) 

Here is the sample theme .property file.

parent=keycloak 
import=common/keycloak 

styles=lib/patternfly/css/patternfly.css lib/zocial/zocial.css css/login.css css/logo.css css/styles.css 
kcHtmlClass=login-pf 
kcContentClass=col-sm-12 col-md-12 col-lg-12 container 
kcContentWrapperClass=row 
kcHeaderClass=col-xs-12 col-sm-8 col-md-8 col-lg-7 
kcFeedbackAreaClass=col-md-12 
kcAlertIconClasserror=pficon pficon-error-circle-o 
kcFormAreaClass=col-xs-12 col-sm-8 col-md-8 col-lg-7 login 
kcFeedbackErrorIcon=pficon pficon-error-circle-o

Change styles related to your theme

Inside of the css directory, you can create style sheets as you preferred. Once you create a stylesheet, it needs to be mentioned in the theme.properties file.

      styles=css/login.css

Change the template structure

• If you want to change the structure of the template, you need to change the related FreeMaker template files.
• There are two ways to change the template.

                     Change the Base template – NOT RECOMMENDED 
                     Override the template and change it – BEST OPTION

• As I mentioned, ‘override the template’ is the best option.
• Just what you need to do is, get a copy from the template file and save it in your theme location.
• Then you can edit saved template according to your requirements and you can add new styles as mentioned above.