How to Create a Custom Login Theme for Keycloak in Docker

1. Introduction

Keycloak is one of the most popular open-source Identity and Access Management platforms backed by RedHat. It is known for its flexibility where complex enterprise use cases don't fit the available cloud authentication platforms.

For this exercise, we will use the project at  https://github.com/czetsuyatech/ct-keycloak-iam, and we should arrive at the following login page.

To do this, we need to familiarise ourselves with the Keycloak theme folder structure to identify the template/CSS files we need to modify.

1.1 Prerequisites

To do this exercise, you must have the following.

• Prior knowledge of Docker
• Keycloak knowledge (<=v16.1.1)
• Knowledge of FreeMarker (for template customization)
• Docker Desktop
• IntelliJ or any other IDE of your choice
• Understanding of CSS / Flex
• Stable internet connection

2. ct-keycloak-iam Project

This project customized Keycloak using Docker. It contains the following folder structure:

• keycloak-docker-assembly
• docker - contains the Dockerfile and compose file
• downloads - copy Keycloak and MySQL JDBC driver here for faster build
• src - contains the keycloak overrides and build tools
• main/resources/themes/czetsuyatech - Keycloak custom theme
• login - custom login page
• docs - usage documentation

*We will only discuss the theme in this exercise, so make sure to comment on the providers' part in keycloak-docker-assembly/src/main/resources/build/build-keycloak.sh

2.1 Running Keycloak in a Docker Container

The project uses a compose file to run the docker container and connect with preconfigured MySQL database.

In the parent directory, run the following command.

docker-compose -f ./keycloak-docker-assembly/docker/docker-compose-dev.yml up --build

This will use the Dockerfile inside the docker folder, and the process will run in the following sequence.

1. Copy the Keycloak resources into the container, including the default realm, MySQL module, theme, providers, and cli & batch scripts.
2. Download the Keycloak server and MySQL driver if they don't exist in the downloads folder.
3. Extract the Keycloak server.
4. Install the following
1. Theme
2. MySQL module and driver
3. Custom providers
4. Custom realm

Open your browser and navigate to:

• Admin - http://localhost:8080, keycloak.admin/keycloak.admin
• Create a user that we can use to log in later.
• User login - http://localhost:8080/auth/realms/czetsuyatech/account

3. Custom Keycloak Theme

Since version 16.1.1, Keycloak has shipped 3 themes:

1. base - basic HTML, almost no styles 
2. keycloak - Keycloak brand, 
3. keycloak.v2 - an extension of #2

We can choose two options if we want to create our own theme. One is to extend the base theme (#1) and provide our own styles, or we can start with the keycloak theme (#2), which is already styled, and start from there. For this exercise, we will go with #2.

I will not discuss the Keycloak Theme in detail as documentation is already available at https://www.keycloak.org/docs/16.1/server_development/#_themes. Instead, we will examine the "login" page.

The login page is structured as follows:

• login
• theme.properties - it contains information about this particular part of the theme, what is its base, the styles, scripts, locale, etc.
• template.ftl - base template for the login pages like sign in, signup, forgot password, OTP, verify email, etc.
• login.ftl - specific page for login
• resources
• CSS - styles
• img - images
• messages - language/translations/localizations
• messages_en.properties

When doing the customization, always think about future-proofing to minimize the effort in the future but still make the login page appealing to the users.

For this exercise, these are our objectives for the login page.

1. Divide the page into two columns.
2. Show a logo on the left side (we can add some background images here).
3. Show a login subtitle (under the Sign in label).

We must understand how the template is laid out and what CSS styles we can override to achieve these goals.

3.1 Here are the CSS tags necessary for the first goal:

• login-pf-page - the parent component
• login-pf-page-header - left component
• card-pf - right component

Using flex, these are the styles.

.login-pf-page {
  padding: 50px;
  display: flex;
  justify-content: center;
  align-items: stretch;
  height: 100%;
}

.login-pf-page-header {
  height: 100%;
  flex: 0 0 35em;
  display: flex;
  flex-direction: column;
  justify-content: space-around;
  border-top-left-radius: 50px;
  border-bottom-left-radius: 50px;
  background-color: #36383a;
}

.card-pf {
  border-top: 0;
  margin: 0;
  flex: 0 0 35em;
  display: flex;
  flex-direction: column;
  justify-content: center;
  border-top-right-radius: 50px;
  border-bottom-right-radius: 50px;
}  

3.2 Show a logo on the left side.

Open the template.ftl file, under the div with id kc-header, add:

<div class="logo">
	<img alt="Czetsuya Tech" src="${url.resourcesPath}/img/ct-logo.svg" width="120"/>
</div>

3.3 Add a sub-title.

Open the login.ftl file, under section=form add:

<div class="login-subtitle" data-qa-id="login-subtitle">${msg("signinIntro")}

Finally, here are the override files: