Documentation

Documentation

Theming

Each SSO provider has its own way of customizing the log-in page, with different features and limitations. Learn how to do this.

Keycloak

Keycloak offers the most control over what can be customized, 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 Vaadin developer would experience using the Login component.

Installation

To use the Keycloak Lumo theme, you need to do a few things: 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 that, 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 on a specific client, go to "Clients" and find the client. At the "Login settings" section, select sso-kit-keycloak-lumo as the "Login theme".

Customizing the Lumo Theme

You can also customize the Lumo theme to suit your application’s branding. To do this, you need to do a couple of things:

First, create this directory structure under the /themes directory of your Keycloak installation:

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

In themes.properties, you need 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 files from the parent theme
styles=css/lumo-common.css css/lumo-styles.css css/my-theme-styles.css

Next, in my-theme-styles.css you can add your styles. For example, you might change the primary color to suit your application’s branding.

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 instructions, see the official Keycloak theme documentation.