Documentation

Documentation

Theming

How to customize a login page.

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

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.