How to create a custom Keycloak Theme

Keycloak themes are a powerful way to customize the appearance and behavior of a Keycloak installation. In this article we will learn how to create a custom Keycloak theme with a baisc CSS knowledge.

Keycloak Themes in a nutshell

Firstly, a Keycloak theme is a set of resources that defines the look and feel of the Keycloak login and registration pages, as well as other pages within the Keycloak application. You can use themes to customize the colors, fonts, and layout of these pages, as well as to add custom JavaScript and CSS code to alter the behavior of the pages.

You can create a Theme from scratch, or you can leverage on one of the built-in Keycloak themes.

Behind the hoods, Keycloak uses Freemarker, which is a template engine that you can use to generate dynamic HTML, XML, or other text-based formats.

Keycloak uses a set of predefined templates to render the various pages within the application.

The default Keycloak themes are packaged inside the org.keycloak.keycloak-themes-<version>.jar file, within the $KEYCLOAK_HOME/lib/lib/main folder. Here is the list of themes which are built-in:

  • base
  • keycloak
  • keycloak.v2

Then, inside each theme you can find the following folders, which you can use to create custom UI for each Keycloak authentication flow:

  • account: This folder contains the definitions for the account console
  • admin: This folder contains the definitions for the administration console
  • common: This folder contains common resources used across theme types
  • email: This folder contains the UI for emails
  • login: This folder contains the UI for login-related pages, including pages for updating profiles, resetting passwords, and so on
  • welcome: Contains the definitions for the welcome page

Now that you have a basic understanding of the default Keycloak themes, in order to create a custom one you have the following options:

  1. Create your own versions of these templates using Freemarker syntax and add static content to it.
  2. Extend the existing keycloak themes, modifying the static content (CSS/images/Javascript) to customize the appearance and behavior of the pages. This is very handy if you just want to make punctual changes to an existing theme.

In this article we will extend the basic Keycloak Templates. In another article we will show a more advanced example of how to create a new set Freemarker templates from scratch.

Anatomy of a Theme

Firstly, you need to understand the structure of a Keycloak theme. Consider the following example:

└── main
    ├── java
    └── resources
        ├── META-INF
        │   ├── keycloak-themes.json
        │   └── services
        └── theme
            └── acme
                └── login
                    ├── resources
                    │   ├── css
                    │   │   ├── bootstrap.min.css
                    │   │   ├──
                    │   │   └── signin.css
                    │   └── img
                    │       ├── favicon.ico
                    │       ├── keycloak-bg.png
                    │       └── keycloak-logo.png

Besides the static content files, there are two main configuration file in a Keycloak theme:

  • The META-INF/keycloak-themes.json
  • The theme/<theme-name>/

Let’s see what is inside these files.

Inside the

Firstly, the file is a configuration file used to customize the appearance and behavior of a Keycloak theme. It is a Java properties file that contains key-value pairs representing various settings for the theme.

Here is the content of this file:


# Define the CSS styles
styles=css/login.css css/bootstrap.min.css css/signin.css


# Mapping styles from Keycloak to those defined in the custom css.
kcButtonDefaultClass=w-100 btn btn-lg btn-primary
kcButtonClass=w-100 btn btn-lg btn-primary
kcFormHeaderClass=h3 mb-3 fw-normal
kcLocaleMainClass=pf-c-dropdown locale-section
kcLocaleListClass=pf-c-dropdown__menu pf-m-align-right

Firstly, notice the parent=keycloak . This property instructs the theme to inherit our login type from the keycloak base theme.

Then, the styles property contains the list of css that you will be using in the keycloak theme. We will be adding the login.css and signin.css on top of the compiled and minified version of the Bootstrap CSS framework.

Next, the meta property is a list of key-value pairs that provide additional information about the theme, such as its name, description, and version.

Finally, we are mapping the Keycloak CSS with the CSS Classes available in our files.

Inside the keycloak-themes.json

The keycloak-themes.json file is a JSON file that contains an array of objects, each representing a theme that is available to Keycloak. Each theme object has a number of properties that define various aspects of the theme, such as its name, display name, and the location of its resources on the file system.

In our example, we will simply define the theme name, which is “acme”:

  "themes": [{
    "name" : "acme",
    "types": [ "login" ]

A more advanced example which includes multiple templates with custom directory resources could be like that:

    "name": "my-theme",
    "displayName": "My Theme",
    "directory": "/path/to/theme/resources"
    "name": "another-theme",
    "displayName": "Another Theme",
    "directory": "/path/to/another/theme/resources"

Editing the CSS files

Finally, we will add a simple customization to the keycloak default theme. Firstly, we will add a background with a custom image in the body. Within the signin.css we will modify the body as follows:

body {
  display: flex;
  align-items: center;
  padding-top: 40px;
  padding-bottom: 40px;
  # Added
  background: url("../img/keycloak-bg.png") no-repeat center center fixed;
  background-size: cover;

Then, we will also add a custom logo in the login-header Class which will display on top of the Login Prompt:

.login-header {
    margin-bottom: 20px !important;
    display: -ms-flexbox !important;
    display: flex !important;
    -ms-flex-direction: column !important;
    flex-direction: column !important;
    color: #000000 !important;
    text-align: center;
    # Added
    background-image: url("../img/keycloak-logo.png") ;

To simplify the deployment of the theme on Keycloak, our project is a Maven project which produces a JAR file. In the next step, we will deploy and test in on Keycloak.

Deploying the Keycloak Theme

Let’s build our “acme” Keycloak theme:

mvn install

Then, we will copy the acme.jar into the providers folder of our Keycloak installation:

cp target/acme.jar $KEYCLOAK_HOME/providers

Finally, rebuild your configuration with the new Keycloak theme:

./ build
Updating the configuration and installing your custom providers, if any. Please wait.
2022-12-31 11:18:48,419 INFO  [io.quarkus.deployment.QuarkusAugmentor] (main) Quarkus augmentation completed in 4263ms

Then, launch Keycloak:

./ start-dev

To test our custom Theme, we recommend using an application realm. For example, create one using the following tutorial: Getting started with Keycloak powered by Quarkus

Then, select the wildfly-realm (from the example).

In your Client configuration, find the Login settings option and choose as Login theme your acme theme:

keycloak custom theme tutorial

Click Save to persist the changes.

You can now access the wildfly-realm from any application. The login prompt (with your customizations) will show up:

how to create a custom keycloak theme


Keycloak themes are a powerful way to customize the appearance and behavior of security checks. In this tutorial we have explored a simple way to extend the basic Keycloak theme with custom static files.

Source code for this article:

Found the article helpful? if so please follow us on Socials