Docs

Docs

Theming

How to customize the log-in page for Vaadin supported authentication providers.

Each SSO provider has its own way of customizing the log-in page, with different features and limitations. This page explains how to customize the log-in 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 themes.properties, 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 my-theme-styles.css 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.