Articles on: Getting Started

Personalize Your Login Interface and Branding (custom theme)

The whole authentication and registration experience along with the email sent can be customized in Keycloak through a custom extension. Examples are available on official keycloak source base or on our github.

Getting started



Let me help you step by step:

👥 First clone this example repository
Then edit the names in ./pom.xml to match your company (these lines)
Rename the directory cloud-iam-redesign in src/main/resources/theme/ with the same name you will put line 3 in src/main/resources/META-INF/keycloak-themes.json (this line)
put inside src/main/resources/theme/{YOUR_DIRECTORY_NAME}/login your theme files — or update the files to match your theme —. Be sure to check that you have a themes.properties file (like this one) in src/main/resources/theme/{YOUR_DIRECTORY_NAME}/login/theme.properties
⏩ run ./build.sh command in the root folder (same folder as pom.xml). If you don't have maven installed, please check this tutorial.
last step 🥁🥁 take the .jar file from ./target folder and upload it on your Cloud-IAM keycloak deployment thanks to the "Upload .jar file" button

Your Keycloak cluster will be automatically redeployed without downtime to enable your theme.

Connect to your Keycloak console to activate your login theme to the realms of your choice.

If you do not wish to do it yourself, please check our consulting services.

Troubleshooting



Theme resources are cached for 30 days in user's browsers how to handle it?



Cloud-IAM follows best web-performance practices. When rolling out a custom Keycloak theme leveraging cache burst with your favorite web bundler (e.g. webpack or parceljs that does it out of the box) is the best way to handle cache invalidation and keep great web performance through asset caching.

Back to the website

Local testing for faster feedback



During the development phase which is often highly iterative, Cloud-IAM recommend using a local version of Keycloak by using for instance a docker container:

docker run --rm -v $HOME/projects/cloud-iam/extensions/keycloak-theme/target/:/opt/keycloak/providers/ \
           -p 8080:8080 -e KC_HTTP_RELATIVE_PATH=/auth \
           -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
           quay.io/keycloak/keycloak:20.0.2 start-dev

Updated on: 18/01/2023

Was this article helpful?

Share your feedback

Cancel

Thank you!