Keycloak Custom Login Theme
A simple guide on how to personalize the standard Keycloak Login Page
As a Software Engineer, we are constantly “hunting” for innovative solutions that can help us develop a better product every day. While the “hunt” can show a clear target, sometimes the task lies in making ours what we just found; and adjusting, customizing, and theming becomes the real challenge.
In today’s article, I would like to talk about Keycloak and show how easy it is to customize the Login Page.
1. What is Keycloak?
Keycloak is an open-source Identity and Access Management solution developed by RedHat that supports:
- Single Sign-On
- OpenID Connect, OAuth 2.0 and SAML 2.0
- LDAP and Active Directory
- User Federation, Identity Brokering and Social Login
- Centralized User Management
2. Setup Keycloak using Docker?
Assuming you have Docker and Docker Compose available in your workspace, let's start by creating a basic Dockerfile and docker-compose.yml files.
While creating a theme it’s a good idea to disable caching as this makes it possible to edit theme resources without restarting Keycloak. That’s why has been added the lines 3 to 5 into Dockerfile definition.
To run the application is enough with docker-compose up and visiting http://localhost:8080/auth/admin/ should show something like:
3. Create a Demo realm
To create a realm, log in first to the Keycloak admin console with username admin and password password, as specifies the docker-compose.yml configuration.
From the Master menu, click on Add realm button, define a name(in this case “demo”) and click on Create.
The Keycloak application should redirect to the Realm Console where all related configuration is available. For now let’s just change the HTML Display name, and enable the Forgot password and Remember Me options under the Login tab.
Open http://localhost:8080/auth/realms/demo/account to check the Realm Login Page and target of this article
4. Add Demo Theme
A Keycloak 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
In this article, the goal is only to customize the Login Page, so let’s start by creating a themes folder and add some basic configuration
Next, let’s extend the Login template from the default theme by running docker cp ck-theme_keycloak:/opt/jboss/keycloak/themes/base/login/login.ftl ./themes/demo/login/login.ftl
And apply the next changes:
Last but not least, add the demo theme as volume to the docker-compose.yml definition.
5. Apply the Demo Theme
To apply the newly created theme to the realm is needed to go again to the Console and under the Theme tab select demo a Login Theme and click on Save.
5. Conclusion
In this article, we learned about Keycloak and how to set up a basic instance using Docker and Docker Compose.
Then we looked at realms and theme creation while extending the default theme.
The next step will be to deploy our Demo Theme by creating an archive for production environment.
To learn more about Keycloak and how to create custom themes, visit https://www.keycloak.org/docs/latest/server_development/#_themes.
As always, the source code is available at https://github.com/alxrodav/keycloak-theme.
