Customized Keycloak.X Login Page

Well done!! You have travelled a long mile in your Keycloak journey. Glad that that you’re ready to customize your login page as per your client branding..

Photo by inlytics | LinkedIn Analytics Tool on Unsplash

Even if you have not started your journey with Keycloak, here is the Getting Started Guide.

Getting Started with Keycloak.X

For traditional Keycloak setup powered by Wildfly we can customize the themes by creating a new directory in the Keycloak “themes” directory. Refer the section as provided by Keycloak Server Developer Guide.

Server Developer Guide

Where is the change in Keycloak.X?

Keycloak.X is a distribution powered by Quarkus, refer to below Getting Started with Keycloak.X Story and YT Video.

Themes customization doesn’t work as it was in traditional Keycloak.

How to customize themes in Keycloak.X

Keycloak support themes for following resources:

Step 1: Create folder with the name of theme you want to have e.g., “pfmninza”.

Step 2: Create folder for the resource which you want to customize. For e.g., “login”. Inside which you need to place folder for resources, where all your files will reside which you want to override from base theme. That is, if you want to update the images only, so put the relevant images in the “img” folder and refer the same in your “js” file.

Similarly you can publish your css changes on top of base theme of Keycloak.

Folder structure for the Custom Theme

Step 3: Create a maven project and under the resources create two folders — META-INF and theme.

Step 4: Under META-INF, create a file with name “keycloak-themes.json” with the content like below. Here we are telling that name of theme is “pfmninza” and type is “login”

{
“themes”: [{
“name” : “pfmninza”,
“types”: [ “login”]
}]
}

Under “theme” folder, paste the folder “pfmninza” that we have done in Step 2.

Strutcure should be something like below with “pom.xml” at the root (which is obvious when we mentioned maven project)

Maven project for custom themes.

Step 5: Run the maven command to build the project and package it as jar archive.

Maven package as jar file

Step 6: Copy the jar file, here “pfmninza-keycloak-theme-0.0.1.jar”, to the “providers” folder in Keycloal.X.

Placing jar file under providers

Step 7: Run “kc.bat config” via cmd or “kc.sh config” via shell. This will consider all the jar files present under providers and configure them in the Keycloak.

Now, if you go to themes tab under Keycloak Security Admin Console, you will be able to find the “pfmninza” theme in the drop-down for “login”.

pfmninza theme in themes selection for login

Here is the final output for “login” page.

Custom Login Page — Material Design

Code for this story can be found in my github repo.

keycloakx-recipes/keycloakx-custom-theme at main · tekgainers/keycloakx-recipes

Thanks a lot for reading and make sure to hit “Clap” if you liked the content.

Happy Reading!!