Tuesday, June 26, 2018

Customizing Keycloak themes

When you 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 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 the Login theme, Account theme, 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 user to edit themes without restarting the Keycloak server.
  • To change this, go to the standalone directory and then go inside configuration.
                    Keycloak -> standalone -> configuration -> standalone.xml
  • There are several files, but 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 Keycloak server is installed.
  • Basically Keycloak server looks like this. Please refer following image.

New themes should be added to themes directory.

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

  • Keycloak theme extends Base theme and it has some specific styles.
  • Documentation says not to edit preloaded themes, instead create your own theme and extends the base theme according to your requirements.
  • You can change themes for account, admin, email, login and welcome pages. Above directory names should be exactly 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 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 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 specify 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. Resources directory contains all resources files such as styles and images. 
  7. theme.properties file contains property definitions.
  8. Go inside of the resources directory and create two directories called css and img. 

What is theme.property file

theme.property file consists 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 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.