loading...
Cover image for How to add custom theme in keycloak

How to add custom theme in keycloak

sandeepbalachandran profile image Sandeep Balachandran Updated on ・5 min read

Hey there,

In the previous we have covered how to install keycloak in local machine

In this one let us look at how we can configure custom theme for keycloak.

Prerequisite

  • Must have an application set up with keycloak.

What we are going to cover here

✅ Theme Types
✅ Default Themes
✅ Creating a Theme
✅ Theme Properties

Theme Types

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

  • Account - Account management

  • Admin - Admin console

  • Email - Emails

  • Login - Login forms

  • Welcome - Welcome page

To change the welcome theme you need to edit standalone.xml, standalone-ha.xml, or domain.xml.
Add welcomeTheme to the theme element,

for example:

<theme>
<welcomeTheme>Theme folder name</welcomeTheme>
</theme>
Enter fullscreen mode Exit fullscreen mode

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

Default Themes

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

Creating a Theme

A theme consists of:

  • HTML templates (Freemarker Templates)

  • Images

  • Message bundles

  • Stylesheets

  • Scripts

  • Theme properties

Side Notes

  • Unless you plan to replace every single page you should extend another theme.
  • Most likely you will want to extend the Keycloak theme,
  • You could also consider extending the base theme if you are significantly changing the look and feel of the pages

  • 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. For theme set staticMaxAge to -1 and both cacheTemplates and cacheThemes to false:

<theme>
    <staticMaxAge>-1</staticMaxAge>
    <cacheThemes>false</cacheThemes>
    <cacheTemplates>false</cacheTemplates>
    ...
</theme>
Enter fullscreen mode Exit fullscreen mode

The file is located in root/standalone/configurations/standalone.xml

You must restart the server for changes to take effect.
  • 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.

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.

theme

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=keycloak
import=common/keycloak
Enter fullscreen mode Exit fullscreen mode

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.

Theme Properties

Theme properties are set in the file /theme.properties in the theme directory.

  • parent - Parent theme to extend

  • import - Import resources from another theme

  • styles - Space-separated list of styles to include

  • locales - Comma-separated list of supported locales

For a list of these properties look at the theme.properties file in the corresponding type of the keycloak theme (themes/keycloak//theme.properties).

When doing so, you can substitute system properties or environment variables by using these formats:

  • ${some.system.property} - for system properties

  • ${env.ENV_VAR} - for environment variables.

A default value can also be provided in case the system property or the environment variable is not found with ${foo:defaultValue}.

HTML Templates

Keycloak uses Freemarker Templates in order to generate HTML. You can override individual templates in your own theme by creating /.ftl. For a list of templates used see themes/base/.

When creating a custom template it is a good idea to copy the template from the base theme to your own theme, then applying the modifications you need.

Bear in mind when upgrading to a new version of Keycloak you may need to update your custom templates to apply changes to the original template if applicable.

Inside login folder create a file called login.ftl and add below code and check the login page.

You can also copy file from the base/login folder . If that the case new theme looks as same as default keycloak login page.

<#import "template.ftl" as layout>
<h1>HELLO WORLD!</h1>
Enter fullscreen mode Exit fullscreen mode

This file can be edited for the necessary changes. It is a FTL file . Check it out more about FTL (Free Marker Template) here

Stylesheets

To add a stylesheet create a file in the /resources/css directory of your theme. Then add it to the styles property in theme.properties.

.login-pf body {
    background: DimGrey none;
}
Enter fullscreen mode Exit fullscreen mode

Then edit themes/mytheme/login/theme.properties and add:

styles=css/styles.css
Enter fullscreen mode Exit fullscreen mode

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

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
Enter fullscreen mode Exit fullscreen mode

Scripts

To add a script create a file in the /resources/js directory of your theme. Then add it to the scripts property in theme.properties

alert('Hello');
Enter fullscreen mode Exit fullscreen mode

Images

To make images available to the theme add them to the /resources/img directory of your theme.

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

or use directly

<img src="${url.resourcesPath}/img/image.jpg">
Enter fullscreen mode Exit fullscreen mode

Messages

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 /messages/messages_en.properties to your theme.

usernameOrEmail=Your Username
Enter fullscreen mode Exit fullscreen mode

Change the theme in keycloak realm settings once edited

change theme

Now go to the login screen of the application

login screeen

Thats it for now. Hasta Pronto ! 🙌🙌

Posted on by:

sandeepbalachandran profile

Sandeep Balachandran

@sandeepbalachandran

Very much interested in working with a space exploration team. Interested in human body anatomy. Currently a dev

Discussion

pic
Editor guide