Docs

Docs

Theming

How to customize the login screen of SSO Kit authentication providers.

Each SSO provider has its own way of customizing the login page, with different features and limitations. This page explains how to customize the login screen for authentication providers.

Keycloak

Keycloak is the most customizable of authentication providers, from the login page to the administration and user dashboards.

SSO Kit offers a custom theme for Keycloak based on Lumo. It gives the provider’s login page a look-and-feel similar to what a Hilla developer would experience using the Login component.

Installation

To use the Keycloak Lumo theme, first download the sso-kit-keycloak-lumo JAR file from Maven.

Next, copy the JAR file into the /providers directory of your Keycloak installation.

Once you’ve done those two steps, you can either set the theme for all or some clients in a realm. To set the theme for all clients, go to Realm Settings › Themes. At the Login Theme selector, choose sso-kit-keycloak-lumo.

To set the theme for a specific client, go to Clients and find that client. At the Login Settings section, select sso-kit-keycloak-lumo as the Login Theme.

Customize the Lumo Theme

You can also customize the Lumo theme to suit your application’s branding. To do this, you need to do a few things: create a directory structure; define some particular properties; and configure CSS. Each of these is described next with examples.

The first step is to create the directory structure, illustrated here, under the /themes directory of your Keycloak installation:

themes/
└── your-theme/
    ├── resources/css/
    │  └── my-theme-styles.css
    └── themes.properties

In the themes.properties file, you have to define some properties such as the parent theme, and load the CSS files:

# Specify the parent theme:
parent=sso-kit-keycloak-lumo
# Load the parent theme files:
styles=css/lumo-common.css css/lumo-styles.css css/my-theme-styles.css

Next, in the my-theme-styles.css file, you can add your styles. For example, you might change the primary color to suit your application’s branding. That could look like this:

html {
  --lumo-primary-color: rgb(22, 138, 72);
  --lumo-primary-color-50pct: rgba(22, 138, 72, 0.704);
}

While working on a custom theme, you might want to disable Keycloak theme caching. You would do that like this:

./bin/kc.bat start-dev --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false

For more information, see the Keycloak theme documentation.